Docs.rs comments
Comments for generating the docs with cargo doc
This commit is contained in:
@@ -3,6 +3,23 @@ use wasm_bindgen_futures::spawn_local;
|
||||
use yew::prelude::*;
|
||||
use yew_router::prelude::*;
|
||||
|
||||
/// The main home page component of the application.
|
||||
///
|
||||
/// This component displays different content based on whether the logged-in user
|
||||
/// is an administrator. It fetches the user's admin status from the
|
||||
/// `/api/users/current` endpoint upon initialization.
|
||||
///
|
||||
/// # Behavior
|
||||
/// - **Loading**: Displays "Loading..." while fetching user data.
|
||||
/// - **Admin User**: Renders the `TicketCount` utility component.
|
||||
/// - **Non-Admin User**: Renders the `TicketCount` utility component.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <Home />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(Home)]
|
||||
pub fn home_component() -> Html {
|
||||
let is_admin = use_state(|| None::<bool>);
|
||||
@@ -44,6 +61,17 @@ pub fn home_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A basic component displayed when a requested route does not match any defined paths (404 error).
|
||||
///
|
||||
/// It provides a simple message indicating that the page was not found and includes
|
||||
/// a link to navigate back to the home page.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <NotFound />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(NotFound)]
|
||||
pub fn not_found_component() -> Html {
|
||||
let message = "404 Not found";
|
||||
@@ -55,6 +83,18 @@ pub fn not_found_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component displayed when a user attempts to access a page for which they do not have sufficient permissions.
|
||||
///
|
||||
/// It informs the user about the access restriction and provides instructions to contact
|
||||
/// a specific person ("Herr Winter") if they believe this is an error.
|
||||
/// It also includes a link to return to the home page.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <PermissionDenied />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(PermissionDenied)]
|
||||
pub fn denied_component() -> Html {
|
||||
html! {
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
//! This module aggregates and re-exports all individual page components of the application.
|
||||
//!
|
||||
//! Each sub-module within `pages` typically represents a distinct view or section
|
||||
//! of the user interface, such as authentication, ticket management, or user profiles.
|
||||
//!
|
||||
//! By re-exporting them here, other parts of the application can import page
|
||||
//! components more conveniently using `crate::pages::*`.
|
||||
pub mod basic_pages;
|
||||
pub mod setup;
|
||||
pub mod sidebar;
|
||||
|
||||
@@ -4,6 +4,17 @@ use wasm_bindgen_futures::spawn_local;
|
||||
use yew::prelude::*;
|
||||
use yew_router::prelude::*;
|
||||
|
||||
/// Payload for creating the initial administrator account.
|
||||
///
|
||||
/// This struct is sent to the `/api/setup-admin` endpoint to create the first admin user
|
||||
/// when no administrators exist in the system. It carries the necessary information
|
||||
/// for the new admin's profile and credentials.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `first_name`: The first name of the administrator.
|
||||
/// - `last_name`: The last name of the administrator.
|
||||
/// - `username`: The unique username for the administrator's login.
|
||||
/// - `pwd`: The password for the administrator's account. This will be hashed on the backend.
|
||||
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
||||
pub struct AdminSetupScheme {
|
||||
pub first_name: String,
|
||||
@@ -12,6 +23,43 @@ pub struct AdminSetupScheme {
|
||||
pub pwd: String,
|
||||
}
|
||||
|
||||
/// Component for the initial admin account setup page.
|
||||
///
|
||||
/// This page is displayed when a fresh system has no administrator accounts. It provides
|
||||
/// a form to create the first admin user. Key functionality:
|
||||
///
|
||||
/// - **Admin Check**: On mount, verifies if an admin already exists by calling `/api/check-admin`.
|
||||
/// If an admin is found, the user is redirected to the login page (`crate::Route::Login`).
|
||||
/// - **Form Fields**: Collects `first_name`, `last_name`, `username`, `password`, and `confirm_password`.
|
||||
/// - **Form Validation**:
|
||||
/// - Ensures password fields are not empty.
|
||||
/// - Verifies that `password` and `confirm_password` match.
|
||||
/// - Ensures the `username` field is not empty.
|
||||
/// - **API Interaction**: On form submission, a POST request is sent to `/api/setup-admin`
|
||||
/// with the new admin's details.
|
||||
/// - **Password Hashing**: The backend is responsible for hashing the password using Argon2
|
||||
/// before storage; this component only sends the plain text password.
|
||||
/// - **Auto-redirect**: On successful admin account creation, the user is automatically
|
||||
/// redirected to the login page (`crate::Route::Login`).
|
||||
/// - **State Management**: Uses Yew's `use_state` hooks to manage:
|
||||
/// - Input field values (`first_name`, `last_name`, `username`, `pwd`, `pwd_confirm`).
|
||||
/// - UI states like `error` messages, `success` status, and `loading` indicators.
|
||||
/// - `admin_check_done` to prevent rendering the form before the initial admin check completes.
|
||||
///
|
||||
/// # Example Flow
|
||||
/// 1. User navigates to `/setup`.
|
||||
/// 2. The component checks `/api/check-admin`.
|
||||
/// 3. If an admin exists, redirects to `/login`.
|
||||
/// 4. If no admin exists, the setup form is displayed.
|
||||
/// 5. User fills out the form and submits.
|
||||
/// 6. Form data is sent via POST to `/api/setup-admin`.
|
||||
/// 7. On successful response (HTTP 200), redirects to `/login`.
|
||||
/// 8. On error, displays an error message to the user.
|
||||
///
|
||||
/// # Security Notes
|
||||
/// - The initial admin check prevents re-creating an admin if one already exists.
|
||||
/// - Password confirmation helps prevent user typos for critical credentials.
|
||||
/// - Backend validation further ensures non-empty and secure credentials.
|
||||
#[component(InitialAdminSetup)]
|
||||
pub fn initial_admin_setup() -> Html {
|
||||
let first_name = use_state(|| "".to_string());
|
||||
|
||||
@@ -9,6 +9,15 @@ use yew_router::prelude::*;
|
||||
|
||||
const STORAGE_KEY: &str = "sidebar_state";
|
||||
|
||||
/// Represents the expansion state of collapsible menus within the sidebar.
|
||||
///
|
||||
/// This struct is used to persist the open/closed state of sidebar submenus,
|
||||
/// improving user experience by remembering their last interaction.
|
||||
/// The state is stored in and retrieved from `LocalStorage`.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `ticket_open`: A boolean indicating if the "Tickets" submenu is expanded (`true`) or collapsed (`false`).
|
||||
/// - `users_open`: A boolean indicating if the "Users" submenu is expanded (`true`) or collapsed (`false`).
|
||||
#[derive(Clone, PartialEq, Serialize, Deserialize)]
|
||||
pub struct SidebarExpandState {
|
||||
pub ticket_open: bool,
|
||||
@@ -16,6 +25,7 @@ pub struct SidebarExpandState {
|
||||
}
|
||||
|
||||
impl Default for SidebarExpandState {
|
||||
/// Provides the default expansion state, where all submenus are collapsed.
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
ticket_open: false,
|
||||
@@ -24,6 +34,17 @@ impl Default for SidebarExpandState {
|
||||
}
|
||||
}
|
||||
|
||||
/// Represents the shared state for the sidebar's expandable menus.
|
||||
///
|
||||
/// This context struct is provided via Yew's `ContextProvider` and allows child components
|
||||
/// within the sidebar to read and modify the expansion state of the "Tickets" and "Users" menus.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `expand`: The current [`SidebarExpandState`] holding whether each menu is open or closed.
|
||||
/// - `set_tickets_open`: A `Callback<bool>` to explicitly set the open state of the "Tickets" menu.
|
||||
/// - `toggle_tickets`: A `Callback<()>` to toggle the open state of the "Tickets" menu.
|
||||
/// - `set_users_open`: A `Callback<bool>` to explicitly set the open state of the "Users" menu.
|
||||
/// - `toggle_users`: A `Callback<()>` to toggle the open state of the "Users" menu.
|
||||
#[derive(Clone, PartialEq)]
|
||||
pub struct SidebarState {
|
||||
pub expand: SidebarExpandState,
|
||||
@@ -34,6 +55,10 @@ pub struct SidebarState {
|
||||
}
|
||||
|
||||
impl SidebarState {
|
||||
/// Creates a new `SidebarState` instance.
|
||||
///
|
||||
/// This constructor is typically used within the [`SidebarStateProvider`] to
|
||||
/// bundle the current expansion state and its associated callbacks for context sharing.
|
||||
fn new(
|
||||
expand: SidebarExpandState,
|
||||
set_tickets_open: Callback<bool>,
|
||||
@@ -51,11 +76,40 @@ impl SidebarState {
|
||||
}
|
||||
}
|
||||
|
||||
/// Properties for components that provide sidebar state.
|
||||
///
|
||||
/// This struct is typically used by context providers that wrap child components
|
||||
/// and supply them with shared sidebar-related state or functionality.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `children`: The child components that will have access to the provided sidebar state.
|
||||
#[derive(Properties, PartialEq)]
|
||||
pub struct SidebarProps {
|
||||
pub children: Children,
|
||||
}
|
||||
|
||||
/// A Yew context provider component that manages and supplies the sidebar's expansion state.
|
||||
///
|
||||
/// This component is responsible for:
|
||||
/// 1. Loading the initial `SidebarExpandState` from browser `LocalStorage` (or using defaults).
|
||||
/// 2. Providing a `SidebarState` context (`Rc<SidebarState>`) to its children, which includes
|
||||
/// the current expansion state and callbacks to modify it.
|
||||
/// 3. Persisting any changes to the `SidebarExpandState` back to `LocalStorage`.
|
||||
///
|
||||
/// Child components (like [`TicketMenu`] and [`UsersMenu`]) can consume this context
|
||||
/// to react to and control the sidebar's collapsible sections.
|
||||
///
|
||||
/// # LocalStorage Key
|
||||
/// The state is stored under the key `STORAGE_KEY` ("sidebar_state").
|
||||
///
|
||||
/// # Example Usage
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <SidebarStateProvider>
|
||||
/// <Sidebar /> // Sidebar and its sub-components will have access to the state
|
||||
/// </SidebarStateProvider>
|
||||
/// }
|
||||
/// ```
|
||||
#[component(SidebarStateProvider)]
|
||||
pub fn sidebar_state_provider(props: &SidebarProps) -> Html {
|
||||
let default = LocalStorage::get(STORAGE_KEY).unwrap_or_else(|_| SidebarExpandState::default());
|
||||
@@ -126,6 +180,27 @@ pub fn sidebar_state_provider(props: &SidebarProps) -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A collapsible menu component for "Tickets" within the sidebar.
|
||||
///
|
||||
/// This component consumes the [`SidebarState`] context to manage its expanded/collapsed state.
|
||||
/// It displays a button to toggle its visibility and, when expanded, reveals links
|
||||
/// for "Submit Ticket" and "View Tickets".
|
||||
///
|
||||
/// # Context
|
||||
/// Requires [`SidebarStateProvider`] as an ancestor to provide the necessary context.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - **Toggle Button**: Clicking the button toggles the `ticket_open` state in the `SidebarState`.
|
||||
/// - **Submenu Links**:
|
||||
/// - [`crate::Route::Ticket`]: Link to submit a new ticket.
|
||||
/// - [`crate::Route::AllTickets`]: Link to view all tickets.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <TicketMenu />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(TicketMenu)]
|
||||
pub fn ticket_menu() -> Html {
|
||||
let ctx =
|
||||
@@ -169,6 +244,27 @@ pub fn ticket_menu() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A collapsible menu component for "Users" within the sidebar.
|
||||
///
|
||||
/// This component consumes the [`SidebarState`] context to manage its expanded/collapsed state.
|
||||
/// It displays a button to toggle its visibility and, when expanded, reveals links
|
||||
/// for "Create User" and "View Users". This menu is typically only visible to administrators.
|
||||
///
|
||||
/// # Context
|
||||
/// Requires [`SidebarStateProvider`] as an ancestor to provide the necessary context.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - **Toggle Button**: Clicking the button toggles the `users_open` state in the `SidebarState`.
|
||||
/// - **Submenu Links**:
|
||||
/// - [`crate::Route::Register`]: Link to create a new user account.
|
||||
/// - [`crate::Route::AllUsers`]: Link to view all registered users.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <UsersMenu />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(UsersMenu)]
|
||||
pub fn users_menu() -> Html {
|
||||
let ctx =
|
||||
@@ -212,6 +308,30 @@ pub fn users_menu() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// The main sidebar component of the application.
|
||||
///
|
||||
/// This component dynamically renders its content based on the user's authentication
|
||||
/// and administrative status. It fetches the current user's details via `/api/users/current`
|
||||
/// to determine what menu items to display.
|
||||
///
|
||||
/// # Structure
|
||||
/// - Wraps its content in a [`SidebarStateProvider`] to allow nested menus to manage their state.
|
||||
/// - Contains a navigation (`<nav>`) element with an unordered list (`<ul>`) of menu items.
|
||||
///
|
||||
/// # Conditional Rendering
|
||||
/// - **Loading**: Displays "Loading..." while fetching user data.
|
||||
/// - **Non-Admin User**: Renders a condensed sidebar including:
|
||||
/// - [`TicketMenu`]: For managing tickets.
|
||||
/// - A "Logout" button.
|
||||
/// - **Admin User**: Renders a full sidebar including:
|
||||
/// - [`TicketMenu`]: For managing tickets.
|
||||
/// - [`UsersMenu`]: For managing user accounts.
|
||||
/// - A direct link to [`crate::Route::Diagnostics`] (Statistiken).
|
||||
/// - A "Logout" button.
|
||||
///
|
||||
/// # Logout Functionality
|
||||
/// The "Logout" button sends a GET request to `/api/logout`, clears the user's session,
|
||||
/// and then redirects the user to the login page (`crate::Route::Login`).
|
||||
#[component(Sidebar)]
|
||||
pub fn sidebar() -> Html {
|
||||
let is_admin = use_state(|| None::<bool>);
|
||||
|
||||
@@ -9,6 +9,13 @@ use web_sys::HtmlSelectElement;
|
||||
use yew::prelude::*;
|
||||
use yew_router::prelude::*;
|
||||
|
||||
/// A hardcoded list of valid room numbers for ticket submissions.
|
||||
///
|
||||
/// This array contains `i16` values representing valid rooms. Negative numbers typically
|
||||
/// denote rooms prefixed with 'K' (e.g., -1 for K1), and numbers greater than or equal to 1000
|
||||
/// denote rooms prefixed with 'D' (e.g., 1001 for D1).
|
||||
///
|
||||
/// This list is used for client-side validation of room input during ticket creation.
|
||||
const VALID_ROOMS: &[i16] = &[
|
||||
1, 2, 3, 4, 5, 6, 7, 8, 9, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23, 24, 25, 26, 27, 28, 29, 30,
|
||||
32, 34, 36, 37, 39, 41, 49, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113,
|
||||
@@ -18,6 +25,16 @@ const VALID_ROOMS: &[i16] = &[
|
||||
-8,
|
||||
];
|
||||
|
||||
/// Data transfer object (DTO) for creating a new ticket.
|
||||
///
|
||||
/// This struct defines the payload sent to the backend when a user submits a new ticket.
|
||||
/// It includes all necessary information for initial ticket creation.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `category`: The category of the ticket (e.g., "Internet", "Hardware").
|
||||
/// - `betreff`: The subject or brief summary of the ticket.
|
||||
/// - `description`: A detailed description of the issue or request.
|
||||
/// - `room`: The room number where the issue is located.
|
||||
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
|
||||
pub struct TicketCreateScheme {
|
||||
pub category: String,
|
||||
@@ -26,11 +43,34 @@ pub struct TicketCreateScheme {
|
||||
pub room: i16,
|
||||
}
|
||||
|
||||
/// Data transfer object (DTO) for updating a ticket's status.
|
||||
///
|
||||
/// This struct is used when sending a request to the backend to change the status
|
||||
/// of an existing ticket.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `status`: The new status of the ticket (e.g., "ToDo", "InProgress", "Completed", "Archived").
|
||||
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
|
||||
pub struct TicketUpdateScheme {
|
||||
pub status: String,
|
||||
}
|
||||
|
||||
/// Represents a complete ticket entity retrieved from the backend.
|
||||
///
|
||||
/// This struct holds all details of a ticket, including its metadata, content,
|
||||
/// and associated user information.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `id`: The unique identifier of the ticket.
|
||||
/// - `category`: The category of the ticket.
|
||||
/// - `betreff`: The subject of the ticket.
|
||||
/// - `description`: The detailed description of the ticket.
|
||||
/// - `room`: The room number associated with the ticket.
|
||||
/// - `status`: The current status of the ticket.
|
||||
/// - `date`: The creation date and time of the ticket in UTC.
|
||||
/// - `user_id`: The ID of the user who created the ticket.
|
||||
/// - `user_first_name`: The first name of the user who created the ticket.
|
||||
/// - `user_last_name`: The last name of the user who created the ticket.
|
||||
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
|
||||
pub struct Ticket {
|
||||
pub id: i32,
|
||||
@@ -45,23 +85,79 @@ pub struct Ticket {
|
||||
pub user_last_name: String,
|
||||
}
|
||||
|
||||
/// Properties for components that display a single ticket.
|
||||
///
|
||||
/// This struct is used to pass the ID of a specific ticket to components
|
||||
/// that need to fetch or display its details.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `id`: The unique identifier of the ticket to be displayed.
|
||||
#[derive(Properties, PartialEq)]
|
||||
pub struct TicketProps {
|
||||
pub id: i32,
|
||||
}
|
||||
|
||||
/// Represents the essential information of the currently authenticated user.
|
||||
///
|
||||
/// This struct is used to hold a subset of user data relevant for client-side
|
||||
/// logic, such as determining if the user is an administrator or filtering
|
||||
/// tickets by their ID.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `id`: An `Option<i16>` holding the unique ID of the active user. `None` if not authenticated or ID is unavailable.
|
||||
/// - `is_admin`: A boolean indicating if the active user has administrator privileges.
|
||||
#[derive(Clone, Debug, PartialEq)]
|
||||
pub struct ActiveUser {
|
||||
pub id: Option<i16>,
|
||||
pub is_admin: bool,
|
||||
}
|
||||
|
||||
/// Represents a standardized error response from the API.
|
||||
///
|
||||
/// This struct is used to deserialize error messages returned by the backend API,
|
||||
/// providing a consistent way to handle and display error information to the user.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `message`: A descriptive error message.
|
||||
/// - `_status`: (Ignored) The HTTP status code or a status string from the API.
|
||||
#[derive(Deserialize, Debug)]
|
||||
struct ApiError {
|
||||
message: String,
|
||||
_status: String,
|
||||
}
|
||||
|
||||
/// A component that provides a form for users to submit new tickets.
|
||||
///
|
||||
/// This component allows users to input details such as category, subject (`betreff`),
|
||||
/// description, and room number for a new support ticket. It includes client-side
|
||||
/// validation for the room number and interacts with the backend API to create the ticket.
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `category`, `betreff`, `description`: Values of the form input fields.
|
||||
/// - `room`, `room_input`: The parsed and raw room numbers, respectively.
|
||||
/// - `status`: To display messages about submission success or errors.
|
||||
///
|
||||
/// # Room Input Handling
|
||||
/// The `room_change` callback handles parsing the room input:
|
||||
/// - Supports numerical room numbers (e.g., "101").
|
||||
/// - Supports 'K' prefixed rooms (e.g., "K1" parses to -1).
|
||||
/// - Supports 'D' prefixed rooms (e.g., "D1" parses to 1001).
|
||||
/// - Validates the parsed room against the `VALID_ROOMS` constant.
|
||||
///
|
||||
/// # Form Submission
|
||||
/// - Prevents default form submission behavior.
|
||||
/// - Performs validation for room number and presence in `VALID_ROOMS`.
|
||||
/// - Constructs a `TicketCreateScheme` payload.
|
||||
/// - Sends a POST request to `/api/tickets/create`.
|
||||
/// - Updates the `status` state based on the API response.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <SubmitTicket />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(SubmitTicket)]
|
||||
pub fn submit_ticket_component() -> Html {
|
||||
let category = use_state(|| "".to_string());
|
||||
@@ -240,6 +336,40 @@ pub fn submit_ticket_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component for displaying, updating, and deleting a single ticket by its ID.
|
||||
///
|
||||
/// This component fetches a specific ticket's details from the backend based on the
|
||||
/// `id` provided in its `TicketProps`. It allows administrators to update the ticket's
|
||||
/// status and delete the ticket.
|
||||
///
|
||||
/// # Props
|
||||
/// - `id`: The `i32` ID of the ticket to fetch and display.
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `ticket`: The fetched [`Ticket`] data, if available.
|
||||
/// - `error`: Any error message encountered during API calls.
|
||||
/// - `loading`: A boolean indicating if data is currently being fetched.
|
||||
/// - `status`: The selected status for updating the ticket.
|
||||
/// - `deleting`: A boolean indicating if a delete operation is in progress.
|
||||
/// - `delete_error`: Any error message from a delete operation.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - **Data Fetching**: On component mount or `id` change, fetches ticket data from
|
||||
/// `/api/tickets/:id`.
|
||||
/// - **Status Update**: Provides a dropdown to change the ticket's status. Submitting the
|
||||
/// form sends a PATCH request to `/api/tickets/:id` with a `TicketUpdateScheme` payload.
|
||||
/// - **Ticket Deletion**: Includes a "Delete" button that, after user confirmation,
|
||||
/// sends a DELETE request to `/api/tickets/:id`. On success, clears the ticket from display.
|
||||
/// - **Error Handling**: Displays error messages for network issues, API errors, or parsing failures.
|
||||
/// - **Date Formatting**: Displays the ticket creation date formatted to `Europe/Berlin` timezone.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <TicketByID id={123} />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(TicketByID)]
|
||||
pub fn ticket_by_id_component(props: &TicketProps) -> Html {
|
||||
let ticket = use_state(|| None::<Ticket>);
|
||||
@@ -423,6 +553,39 @@ pub fn ticket_by_id_component(props: &TicketProps) -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component for fetching and displaying a list of all tickets.
|
||||
///
|
||||
/// This component retrieves all tickets from the backend and presents them as a list.
|
||||
/// It dynamically filters the displayed tickets based on the current user's role:
|
||||
/// administrators see all tickets, while regular users only see tickets they created.
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `tickets`: A vector of `Ticket` structs to store the fetched tickets.
|
||||
/// - `error`: Any error message encountered during API calls.
|
||||
/// - `loading`: A boolean indicating if data is currently being fetched.
|
||||
/// - `user`: An `ActiveUser` struct holding the current user's ID and admin status.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - **Fetch Tickets**: On component mount, fetches all tickets from `/api/tickets`.
|
||||
/// - **Fetch Current User**: Concurrently fetches the current user's details from
|
||||
/// `/api/users/current` to determine their `user_id` and `is_admin` status.
|
||||
/// - **Conditional Display**:
|
||||
/// - If `loading` is true, displays "Loading...".
|
||||
/// - If an `error` occurs, displays the error message.
|
||||
/// - Otherwise, renders a list of tickets.
|
||||
/// - **Filtering**:
|
||||
/// - Administrators (`user.is_admin = true`) see all tickets.
|
||||
/// - Regular users (`user.is_admin = false`) only see tickets where `t.user_id == user.id`.
|
||||
/// - **Navigation**: Each ticket in the list is a link to [`crate::Route::TicketById`]
|
||||
/// for viewing individual ticket details.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <AllTickets />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(AllTickets)]
|
||||
pub fn all_tickets_component() -> Html {
|
||||
let tickets = use_state(|| Vec::<Ticket>::new());
|
||||
|
||||
@@ -14,6 +14,17 @@ use yew_router::prelude::*;
|
||||
// pub pwd: String,
|
||||
// }
|
||||
|
||||
/// Data transfer object (DTO) for creating a new user.
|
||||
///
|
||||
/// This struct defines the payload sent to the backend when an administrator
|
||||
/// registers a new user. It includes all necessary information for user creation.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `first_name`: The first name of the user.
|
||||
/// - `last_name`: The last name of the user.
|
||||
/// - `username`: The unique username for the user's login.
|
||||
/// - `is_admin`: A boolean indicating whether the new user should have administrator privileges.
|
||||
/// - `pwd`: The password for the user's account. This will be hashed on the backend.
|
||||
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
||||
pub struct UserCreateScheme {
|
||||
pub first_name: String,
|
||||
@@ -23,12 +34,31 @@ pub struct UserCreateScheme {
|
||||
pub pwd: String,
|
||||
}
|
||||
|
||||
/// Data transfer object (DTO) for user login credentials.
|
||||
///
|
||||
/// This struct defines the payload sent to the backend when a user attempts to log in.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `username`: The username provided by the user.
|
||||
/// - `pwd`: The password provided by the user.
|
||||
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
||||
pub struct LoginScheme {
|
||||
pub username: String,
|
||||
pub pwd: String,
|
||||
}
|
||||
|
||||
/// Data transfer object (DTO) for updating an existing user's information.
|
||||
///
|
||||
/// This struct is used to send updated user details, including an optional new password,
|
||||
/// to the backend for an existing user.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `id`: The unique identifier of the user to be updated.
|
||||
/// - `first_name`: The updated first name of the user.
|
||||
/// - `last_name`: The updated last name of the user.
|
||||
/// - `username`: The updated username for the user.
|
||||
/// - `make_admin`: A boolean indicating whether to grant/revoke administrator privileges.
|
||||
/// - `new_pwd`: An optional new password for the user. If empty, the password remains unchanged.
|
||||
#[derive(Deserialize, Serialize, Debug)]
|
||||
pub struct UserUpdateScheme {
|
||||
pub id: i16,
|
||||
@@ -39,6 +69,18 @@ pub struct UserUpdateScheme {
|
||||
pub new_pwd: String,
|
||||
}
|
||||
|
||||
/// Represents a user entity with sensitive information filtered out.
|
||||
///
|
||||
/// This struct is used for displaying user information in contexts where
|
||||
/// the password hash or other sensitive details are not needed or should not be exposed.
|
||||
/// It's typically used for listing users or displaying user profiles.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `id`: The unique identifier of the user.
|
||||
/// - `first_name`: The first name of the user.
|
||||
/// - `last_name`: The last name of the user.
|
||||
/// - `username`: The unique username of the user.
|
||||
/// - `is_admin`: A boolean indicating if the user has administrator privileges.
|
||||
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
||||
pub struct FilteredUser {
|
||||
pub id: i16,
|
||||
@@ -48,6 +90,13 @@ pub struct FilteredUser {
|
||||
pub is_admin: bool,
|
||||
}
|
||||
|
||||
/// Properties for components that display or interact with a single user.
|
||||
///
|
||||
/// This struct is used to pass the ID of a specific user to components
|
||||
/// that need to fetch, display, or modify their details.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `id`: The unique identifier of the user to be displayed or acted upon.
|
||||
#[derive(Properties, PartialEq)]
|
||||
pub struct UserProps {
|
||||
pub id: i16,
|
||||
@@ -59,6 +108,31 @@ struct ApiError {
|
||||
_status: String,
|
||||
}
|
||||
|
||||
/// A component providing a form for registering new users.
|
||||
///
|
||||
/// This component allows an administrator to create new user accounts by providing
|
||||
/// their first name, last name, username, password, and specifying if they should
|
||||
/// be an administrator. The component handles form input, validation (basic),
|
||||
/// and interaction with the backend `/api/register` endpoint.
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `first_name`, `last_name`, `username`, `pwd`: Values of the form input fields.
|
||||
/// - `is_admin`: Boolean state for the admin checkbox.
|
||||
/// - `status`: To display messages about registration success or errors.
|
||||
///
|
||||
/// # Form Submission
|
||||
/// - Prevents default form submission behavior.
|
||||
/// - Constructs a `UserCreateScheme` payload from the form data.
|
||||
/// - Sends a POST request to `/api/register`.
|
||||
/// - Updates the `status` state based on the API response.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <Register />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(Register)]
|
||||
pub fn register_component() -> Html {
|
||||
let first_name = use_state(|| "".to_string());
|
||||
@@ -169,6 +243,32 @@ pub fn register_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component providing a form for user login.
|
||||
///
|
||||
/// This component handles user authentication by collecting a username and password,
|
||||
/// then sending these credentials to the backend `/api/login` endpoint. It manages
|
||||
/// UI states for loading, errors, and success, and redirects to the home page on successful login.
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `username`, `pwd`: Values of the login form input fields.
|
||||
/// - `loading`: A boolean to indicate if the login process is ongoing.
|
||||
/// - `error`: A string to display any login error messages.
|
||||
/// - `success`: A boolean to indicate if login was successful.
|
||||
///
|
||||
/// # Form Submission
|
||||
/// - Prevents default form submission behavior.
|
||||
/// - Constructs a `LoginScheme` payload from the input fields.
|
||||
/// - Sends a POST request to `/api/login`.
|
||||
/// - On successful response (HTTP 200), sets `success` to true and redirects to `crate::Route::Home`.
|
||||
/// - On error, updates the `error` state with the appropriate message.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <Login />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(Login)]
|
||||
pub fn login_component() -> Html {
|
||||
let username = use_state(|| "".to_string());
|
||||
@@ -252,6 +352,33 @@ pub fn login_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component for fetching and displaying a list of all registered users.
|
||||
///
|
||||
/// This component retrieves a list of `FilteredUser` entities from the backend
|
||||
/// via the `/api/users` endpoint and displays them. Each user entry includes a
|
||||
/// link to view their individual details through `UserByID`.
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `users`: A vector of `FilteredUser` structs to store the fetched user data.
|
||||
/// - `error`: Any error message encountered during API calls.
|
||||
/// - `loading`: A boolean indicating if user data is currently being fetched.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - **Data Fetching**: On component mount, fetches all users from `/api/users`.
|
||||
/// - **Conditional Display**:
|
||||
/// - If `loading` is true, displays "Loading...".
|
||||
/// - If an `error` occurs, displays the error message.
|
||||
/// - Otherwise, renders an unordered list of users.
|
||||
/// - **Navigation**: Each user in the list is a link to [`crate::Route::UserByID`]
|
||||
/// for viewing individual user details.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <AllUsers />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(AllUsers)]
|
||||
pub fn all_users_component() -> Html {
|
||||
let users = use_state(|| Vec::<FilteredUser>::new());
|
||||
@@ -306,6 +433,43 @@ pub fn all_users_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component for displaying, updating, and deleting a single user by their ID.
|
||||
///
|
||||
/// This component fetches a specific user's details from the backend based on the
|
||||
/// `id` provided in its `UserProps`. It allows administrators to view, modify
|
||||
/// (first name, last name, username, admin status, and password), and delete user accounts.
|
||||
///
|
||||
/// # Props
|
||||
/// - `id`: The `i16` ID of the user to fetch and display.
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `user`: The fetched [`FilteredUser`] data, if available.
|
||||
/// - `error`: Any error message encountered during initial user data fetching.
|
||||
/// - `loading`: A boolean indicating if initial user data is being fetched.
|
||||
/// - `first_name`, `last_name`, `username`, `make_admin`, `new_pwd`:
|
||||
/// States for the update form fields, pre-filled with current user data.
|
||||
/// - `saving`, `save_error`, `save_success`: States for the user update operation.
|
||||
/// - `deleting`, `delete_error`: States for the user deletion operation.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - **Initial Data Fetching**: On component mount or `id` change, fetches user data from
|
||||
/// `/api/users/:id`.
|
||||
/// - **Form Initialization**: Populates the update form fields with the fetched user's
|
||||
/// current details once loaded.
|
||||
/// - **User Update**: The update form sends a PATCH request to `/api/users/:id` with a
|
||||
/// `UserUpdateScheme` payload. On success, updates the displayed user data and shows a
|
||||
/// success message.
|
||||
/// - **User Deletion**: Includes a "Delete" button that, after user confirmation, sends
|
||||
/// a DELETE request to `/api/users/:id`. On success, clears the user from display.
|
||||
/// - **Error Handling**: Displays error messages for various API and network issues.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <UserByID id={42} />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(UserByID)]
|
||||
pub fn user_by_id_component(props: &UserProps) -> Html {
|
||||
let user = use_state(|| None::<FilteredUser>);
|
||||
|
||||
@@ -8,17 +8,42 @@ use yew::prelude::*;
|
||||
|
||||
use crate::pages::ticket::{ActiveUser, Ticket};
|
||||
|
||||
/// A partial representation of a ticket, containing only the fields necessary for statistical analysis.
|
||||
///
|
||||
/// This struct is used to efficiently retrieve and process ticket data for diagnostics
|
||||
/// without fetching the full ticket details.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `date`: The creation date and time of the ticket in UTC.
|
||||
/// - `room`: The room number associated with the ticket.
|
||||
#[derive(Debug, Deserialize, Clone, PartialEq)]
|
||||
struct TicketPartial {
|
||||
date: DateTime<Utc>,
|
||||
room: i16,
|
||||
}
|
||||
|
||||
/// Properties for components that display room-wise ticket totals.
|
||||
///
|
||||
/// This struct passes a list of partial ticket data to a component responsible
|
||||
/// for calculating and visualizing ticket distribution per room.
|
||||
///
|
||||
/// # Fields
|
||||
/// - `tickets`: A vector of `TicketPartial` containing ticket data relevant for room totals.
|
||||
#[derive(Properties, PartialEq)]
|
||||
struct RoomTotalsProps {
|
||||
tickets: Vec<TicketPartial>,
|
||||
}
|
||||
|
||||
/// Converts a `chrono::DateTime<Utc>` object's weekday to a 0-indexed integer.
|
||||
///
|
||||
/// This function maps `chrono::Weekday` values (where Monday is 1, Sunday is 7)
|
||||
/// to a 0-indexed system (Monday = 0, Sunday = 6).
|
||||
///
|
||||
/// # Arguments
|
||||
/// - `dt`: A reference to a `DateTime<Utc>` object.
|
||||
///
|
||||
/// # Returns
|
||||
/// A `usize` representing the weekday index (0 for Monday, ..., 6 for Sunday).
|
||||
fn weekday_index(dt: &DateTime<Utc>) -> usize {
|
||||
// chrono::Weekday: Mon = 1 ... Sun = 7
|
||||
match dt.weekday() {
|
||||
@@ -32,6 +57,17 @@ fn weekday_index(dt: &DateTime<Utc>) -> usize {
|
||||
}
|
||||
}
|
||||
|
||||
/// Counts the number of tickets submitted on each day of the week.
|
||||
///
|
||||
/// This function takes a slice of `TicketPartial` and returns an array where each
|
||||
/// element corresponds to a day of the week (Monday=0, Sunday=6) and contains
|
||||
/// the total count of tickets submitted on that day.
|
||||
///
|
||||
/// # Arguments
|
||||
/// - `tickets`: A slice of `TicketPartial` items to count.
|
||||
///
|
||||
/// # Returns
|
||||
/// An array `[usize; 7]` with ticket counts for each weekday.
|
||||
fn count_by_weekday(tickets: &[TicketPartial]) -> [usize; 7] {
|
||||
let mut counts = [0usize; 7];
|
||||
for t in tickets {
|
||||
@@ -40,6 +76,18 @@ fn count_by_weekday(tickets: &[TicketPartial]) -> [usize; 7] {
|
||||
counts
|
||||
}
|
||||
|
||||
/// Calculates the occurrences of each weekday within the date range covered by the tickets.
|
||||
///
|
||||
/// This function determines the minimum and maximum dates from the provided `TicketPartial`
|
||||
/// slice and then counts how many times each weekday occurs within that inclusive date range.
|
||||
/// This is useful for normalizing ticket counts against the number of available days for each weekday.
|
||||
///
|
||||
/// # Arguments
|
||||
/// - `partials`: A slice of `TicketPartial` items defining the date range.
|
||||
///
|
||||
/// # Returns
|
||||
/// An array `[usize; 7]` where each element represents the number of times a
|
||||
/// specific weekday (Monday=0, ..., Sunday=6) appears in the date range.
|
||||
fn day_counts(partials: &[TicketPartial]) -> [usize; 7] {
|
||||
if partials.is_empty() {
|
||||
return [0usize; 7];
|
||||
@@ -82,6 +130,17 @@ fn day_counts(partials: &[TicketPartial]) -> [usize; 7] {
|
||||
occ
|
||||
}
|
||||
|
||||
/// Converts a numerical room representation back into a human-readable string format.
|
||||
///
|
||||
/// This function is the inverse of the room parsing logic in `SubmitTicket` component.
|
||||
/// It converts negative numbers back to "K" prefixed rooms, numbers >= 1000 back to "D" prefixed rooms,
|
||||
/// and other numbers to their string representation.
|
||||
///
|
||||
/// # Arguments
|
||||
/// - `r`: An `i16` representing the internal numerical representation of a room.
|
||||
///
|
||||
/// # Returns
|
||||
/// A `String` containing the formatted room number (e.g., "K1", "D1", "101").
|
||||
fn parse_room(r: i16) -> String {
|
||||
if r < 0 {
|
||||
format!("K{}", r.abs())
|
||||
@@ -92,6 +151,21 @@ fn parse_room(r: i16) -> String {
|
||||
}
|
||||
}
|
||||
|
||||
/// The main diagnostics dashboard component.
|
||||
///
|
||||
/// This component serves as a container for various statistical and diagnostic
|
||||
/// views related to the application's tickets.
|
||||
///
|
||||
/// # Components Rendered
|
||||
/// - [`TicketCount`]: Displays the count of open tickets.
|
||||
/// - [`SubmitStats`]: Displays statistics related to ticket submissions (e.g., by weekday, by room).
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <Diagnostics />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(Diagnostics)]
|
||||
pub fn diagnostics_component() -> Html {
|
||||
html! {
|
||||
@@ -102,6 +176,31 @@ pub fn diagnostics_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component that displays the count of currently open (ToDo or InProgress) tickets.
|
||||
///
|
||||
/// This component fetches all tickets and the current user's details. It then filters
|
||||
/// the tickets to count only those that are "ToDo" or "InProgress" and are either
|
||||
/// created by the current user (for non-admins) or all tickets (for admins).
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `tickets`: A vector of `Ticket` structs for all fetched tickets.
|
||||
/// - `error`: Any error message from API calls.
|
||||
/// - `loading`: A boolean indicating if data is being fetched.
|
||||
/// - `user`: The `ActiveUser` details for conditional filtering.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - Fetches all tickets from `/api/tickets`.
|
||||
/// - Fetches current user details from `/api/users/current`.
|
||||
/// - Filters tickets by status ("ToDo" or "InProgress") and user ID (if not admin).
|
||||
/// - Displays the count of matching tickets.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <TicketCount />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(TicketCount)]
|
||||
pub fn ticket_count_component() -> Html {
|
||||
let tickets = use_state(|| Vec::<Ticket>::new());
|
||||
@@ -196,6 +295,33 @@ pub fn ticket_count_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component that displays various statistics about ticket submissions.
|
||||
///
|
||||
/// This component fetches all tickets (in a partial format for efficiency)
|
||||
/// and calculates statistics such as tickets per weekday and tickets per room.
|
||||
/// It renders these statistics visually using simple bar charts.
|
||||
///
|
||||
/// # State
|
||||
/// Uses `use_state` hooks to manage:
|
||||
/// - `tickets`: A vector of `TicketPartial` for statistical analysis.
|
||||
/// - `error`: Any error message from API calls.
|
||||
/// - `loading`: A boolean indicating if data is being fetched.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - Fetches all tickets (as `TicketPartial`) from `/api/tickets`.
|
||||
/// - Calculates:
|
||||
/// - `counts`: Number of tickets submitted on each weekday.
|
||||
/// - `occ`: Number of occurrences of each weekday in the ticket date range.
|
||||
/// - `avg`: Average number of tickets per day for each weekday, normalized by `occ`.
|
||||
/// - Renders a bar chart for average tickets per weekday.
|
||||
/// - Renders a [`RoomTotalTickets`] component to display tickets per room.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <SubmitStats />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(SubmitStats)]
|
||||
pub fn submit_stats_component() -> Html {
|
||||
let tickets = use_state(|| Vec::<TicketPartial>::new());
|
||||
@@ -293,6 +419,29 @@ pub fn submit_stats_component() -> Html {
|
||||
}
|
||||
}
|
||||
|
||||
/// A component that displays the total number of tickets per room.
|
||||
///
|
||||
/// This component takes a list of `TicketPartial` items and calculates the
|
||||
/// total number of tickets for each room. It then displays these totals
|
||||
/// in a sorted list with a bar chart visualization.
|
||||
///
|
||||
/// # Props
|
||||
/// - `tickets`: A `Vec<TicketPartial>` containing the partial ticket data for analysis.
|
||||
///
|
||||
/// # Functionality
|
||||
/// - **Calculates Totals**: Aggregates ticket counts for each unique room.
|
||||
/// - **Sorts Results**: Displays rooms sorted by ticket count in descending order.
|
||||
/// - **Visualizes Data**: Renders a bar chart where the width of each bar is
|
||||
/// proportional to the ticket count for that room, relative to the room with the maximum tickets.
|
||||
/// - **Room Formatting**: Uses the `parse_room` function to display room numbers
|
||||
/// in a human-readable format.
|
||||
///
|
||||
/// # Example
|
||||
/// ```rust
|
||||
/// html! {
|
||||
/// <RoomTotalTickets tickets={my_ticket_partials} />
|
||||
/// }
|
||||
/// ```
|
||||
#[component(RoomTotalTickets)]
|
||||
fn room_total_component(props: &RoomTotalsProps) -> Html {
|
||||
let mut totals: HashMap<i16, usize> = HashMap::new();
|
||||
|
||||
Reference in New Issue
Block a user