Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:44:11Z

Aapai: /* 1. View Submissions Page */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== 1. View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API, developed required backend for the task.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for "Assign Grade" and "View History".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang="json">
[
{
"id": 9,
"name": "Texas penguins",
"team_id": 9,
"topic": "Progressive fresh-thinking middleware",
"members": [
{ "id": 20, "name": "erlinda.grimes" },
{ "id": 21, "name": "lawanda.wilkinson" }
]
}
]
</syntaxhighlight>

=== Seeding Changes ===

To test the View Submissions feature thoroughly, we updated `db/seeds.rb` to include realistic assignments, topics, teams, and student-user mappings.

<syntaxhighlight lang="ruby">
# SignUpTopics
signup_topics = assignments.flat_map do |assignment|
5.times.map do
SignUpTopic.create!(
topic_name: Faker::Company.catch_phrase,
assignment_id: assignment.id,
max_choosers: 2,
category: "Default",
topic_identifier: Faker::Alphanumeric.alpha(number: 8).upcase,
description: Faker::Lorem.sentence
)
end
end

# SignedUpTeams
teams.each_with_index do |team, idx|
SignedUpTeam.create!(
sign_up_topic_id: signup_topics[idx % signup_topics.length].id,
team_id: team.id,
is_waitlisted: false,
preference_priority_number: 1
)
end

# Participants
students.each_with_index do |student, idx|
Participant.create!(
user_id: student.id,
assignment_id: assignments[idx % assignments.length].id,
team_id: teams[idx % teams.length].id
)
end
</syntaxhighlight>

* Ensures every team has students, a valid assignment, and a topic
* Prepares data for consistent API response
* Essential for local testing and API verification

This implementation was inspired by prior work in the Expertiza backend [https://github.com/expertiza/reimplementation-back-end/pull/173 (PR #173)], and extended in our custom implementation documented here: [https://github.com/expertiza/reimplementation-back-end/pull/190 (PR #190)].

=== UI Previews ===
Visual confirmation of the working interface with accessible design, action buttons, and responsive layout.

==== View Assignments Page ====

'''1. Desktop View'''
[[File:ass-1-ui.png|800px|center]]

'''2. Mobile View'''
[[File:ass-1-ui-2.png|400px|center]]

'''3. Network Request'''
[[File:ass-1-net-1.png|800px|center]]

=== View Submissions Page ===

'''1. Desktop View'''
[[File:ass-2-ui.png|800px|center]]

'''2. Mobile View'''
[[File:ass-2-ui-2.png|400px|center]]

'''3. Network Request'''
[[File:ass-2-net-1.png|800px|center]]

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:43:27Z

Aapai: /* 1. View Submissions Page */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== 1. View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API, developed required backend for the task.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for "Assign Grade" and "View History".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang="json">
[
{
"id": 9,
"name": "Texas penguins",
"team_id": 9,
"topic": "Progressive fresh-thinking middleware",
"members": [
{ "id": 20, "name": "erlinda.grimes" },
{ "id": 21, "name": "lawanda.wilkinson" }
]
}
]
</syntaxhighlight>

=== Seeding Changes ===

To test the View Submissions feature thoroughly, we updated `db/seeds.rb` to include realistic assignments, topics, teams, and student-user mappings.

<syntaxhighlight lang="ruby">
# SignUpTopics
signup_topics = assignments.flat_map do |assignment|
5.times.map do
SignUpTopic.create!(
topic_name: Faker::Company.catch_phrase,
assignment_id: assignment.id,
max_choosers: 2,
category: "Default",
topic_identifier: Faker::Alphanumeric.alpha(number: 8).upcase,
description: Faker::Lorem.sentence
)
end
end

# SignedUpTeams
teams.each_with_index do |team, idx|
SignedUpTeam.create!(
sign_up_topic_id: signup_topics[idx % signup_topics.length].id,
team_id: team.id,
is_waitlisted: false,
preference_priority_number: 1
)
end

# Participants
students.each_with_index do |student, idx|
Participant.create!(
user_id: student.id,
assignment_id: assignments[idx % assignments.length].id,
team_id: teams[idx % teams.length].id
)
end
</syntaxhighlight>

* Ensures every team has students, a valid assignment, and a topic
* Prepares data for consistent API response
* Essential for local testing and API verification

This implementation was inspired by prior work in the Expertiza backend [https://github.com/expertiza/reimplementation-back-end/pull/173 (PR #173)], and extended in our custom implementation documented here: [https://github.com/expertiza/reimplementation-back-end/pull/190 (PR #190)].

=== UI Previews ===
Visual confirmation of the working interface with accessible design, action buttons, and responsive layout.

==== View Assignments Page ====

'''1. Desktop View'''
[[File:ass-1-ui.png|800px|center]]

'''2. Mobile View'''
[[File:ass-1-ui-2.png|400px|center]]

'''3. Network Request'''
[[File:ass-1-net-1.png|800px|center]]

=== View Submissions Page ===

'''4. Desktop View'''
[[File:ass-2-ui.png|800px|center]]

'''5. Mobile View'''
[[File:ass-2-ui-2.png|400px|center]]

'''6. Network Request'''
[[File:ass-2-net-1.png|800px|center]]

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

File:Ass-2-ui-2.png

2025-04-20T06:40:58Z

Aapai:

File:Ass-1-ui-2.png

2025-04-20T06:40:40Z

Aapai:

File:Ass-2-net-1.png

2025-04-20T06:38:31Z

Aapai:

File:Ass-2-ui.png

2025-04-20T06:37:39Z

Aapai:

File:Ass-1-net-1.png

2025-04-20T06:36:26Z

Aapai:

File:Ass-1-ui.png

2025-04-20T06:34:14Z

Aapai:

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:29:21Z

Aapai: /* 1. View Submissions Page */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== 1. View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API, developed required backend for the task.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for "Assign Grade" and "View History".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang="json">
[
{
"id": 9,
"name": "Texas penguins",
"team_id": 9,
"topic": "Progressive fresh-thinking middleware",
"members": [
{ "id": 20, "name": "erlinda.grimes" },
{ "id": 21, "name": "lawanda.wilkinson" }
]
}
]
</syntaxhighlight>

=== Seeding Changes ===

To test the View Submissions feature thoroughly, we updated `db/seeds.rb` to include realistic assignments, topics, teams, and student-user mappings.

<syntaxhighlight lang="ruby">
# SignUpTopics
signup_topics = assignments.flat_map do |assignment|
5.times.map do
SignUpTopic.create!(
topic_name: Faker::Company.catch_phrase,
assignment_id: assignment.id,
max_choosers: 2,
category: "Default",
topic_identifier: Faker::Alphanumeric.alpha(number: 8).upcase,
description: Faker::Lorem.sentence
)
end
end

# SignedUpTeams
teams.each_with_index do |team, idx|
SignedUpTeam.create!(
sign_up_topic_id: signup_topics[idx % signup_topics.length].id,
team_id: team.id,
is_waitlisted: false,
preference_priority_number: 1
)
end

# Participants
students.each_with_index do |student, idx|
Participant.create!(
user_id: student.id,
assignment_id: assignments[idx % assignments.length].id,
team_id: teams[idx % teams.length].id
)
end
</syntaxhighlight>

* Ensures every team has students, a valid assignment, and a topic
* Prepares data for consistent API response
* Essential for local testing and API verification

This implementation was inspired by prior work in the Expertiza backend [https://github.com/expertiza/reimplementation-back-end/pull/173 (PR #173)], and extended in our custom implementation documented here: [https://github.com/expertiza/reimplementation-back-end/pull/190 (PR #190)].

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:25:00Z

Aapai: /* 1. View Submissions Page */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== 1. View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API, developed required backend for the task.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for "Assign Grade" and "View History".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang="json">
[
{
"id": 9,
"name": "Texas penguins",
"team_id": 9,
"topic": "Progressive fresh-thinking middleware",
"members": [
{ "id": 20, "name": "erlinda.grimes" },
{ "id": 21, "name": "lawanda.wilkinson" }
]
}
]
</syntaxhighlight>

=== Seeding Changes ===

To test the View Submissions feature thoroughly, we updated `db/seeds.rb` to include realistic assignments, topics, teams, and student-user mappings.

<syntaxhighlight lang="ruby">
# SignUpTopics
signup_topics = assignments.flat_map do |assignment|
5.times.map do
SignUpTopic.create!(
topic_name: Faker::Company.catch_phrase,
assignment_id: assignment.id,
max_choosers: 2,
category: "Default",
topic_identifier: Faker::Alphanumeric.alpha(number: 8).upcase,
description: Faker::Lorem.sentence
)
end
end

# SignedUpTeams
teams.each_with_index do |team, idx|
SignedUpTeam.create!(
sign_up_topic_id: signup_topics[idx % signup_topics.length].id,
team_id: team.id,
is_waitlisted: false,
preference_priority_number: 1
)
end

# Participants
students.each_with_index do |student, idx|
Participant.create!(
user_id: student.id,
assignment_id: assignments[idx % assignments.length].id,
team_id: teams[idx % teams.length].id
)
end
</syntaxhighlight>

* Ensures every team has students, a valid assignment, and a topic
* Prepares data for consistent API response
* Essential for local testing and API verification

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:23:27Z

Aapai: /* Key Features */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== 1. View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API, developed required backend for the task.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for "Assign Grade" and "View History".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang="json">
[
{
"id": 9,
"name": "Texas penguins",
"team_id": 9,
"topic": "Progressive fresh-thinking middleware",
"members": [
{ "id": 20, "name": "erlinda.grimes" },
{ "id": 21, "name": "lawanda.wilkinson" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:22:16Z

Aapai: /* View Submissions Page */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== 1. View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for "Assign Grade" and "View History".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang="json">
[
{
"id": 9,
"name": "Texas penguins",
"team_id": 9,
"topic": "Progressive fresh-thinking middleware",
"members": [
{ "id": 20, "name": "erlinda.grimes" },
{ "id": 21, "name": "lawanda.wilkinson" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:21:43Z

Aapai: /* Key Features */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for "Assign Grade" and "View History".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang="json">
[
{
"id": 9,
"name": "Texas penguins",
"team_id": 9,
"topic": "Progressive fresh-thinking middleware",
"members": [
{ "id": 20, "name": "erlinda.grimes" },
{ "id": 21, "name": "lawanda.wilkinson" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:20:16Z

Aapai: /* Sample JSON Response */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for \"Assign Grade\" and \"View History\".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang="json">
[
{
"id": 9,
"name": "Texas penguins",
"team_id": 9,
"topic": "Progressive fresh-thinking middleware",
"members": [
{ "id": 20, "name": "erlinda.grimes" },
{ "id": 21, "name": "lawanda.wilkinson" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:19:19Z

Aapai: /* Backend Controller Code */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for \"Assign Grade\" and \"View History\".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: "Assignment not found" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang=\"json\">
[
{
\"id\": 9,
\"name\": \"Texas penguins\",
\"team_id\": 9,
\"topic\": \"Progressive fresh-thinking middleware\",
\"members\": [
{ \"id\": 20, \"name\": \"erlinda.grimes\" },
{ \"id\": 21, \"name\": \"lawanda.wilkinson\" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:19:02Z

Aapai: /* Backend Controller Code */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for \"Assign Grade\" and \"View History\".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang="ruby">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: \"Assignment not found\" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang=\"json\">
[
{
\"id\": 9,
\"name\": \"Texas penguins\",
\"team_id\": 9,
\"topic\": \"Progressive fresh-thinking middleware\",
\"members\": [
{ \"id\": 20, \"name\": \"erlinda.grimes\" },
{ \"id\": 21, \"name\": \"lawanda.wilkinson\" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:17:58Z

Aapai: /* API Documentation */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for \"Assign Grade\" and \"View History\".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang=\"ruby\">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: \"Assignment not found\" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.177.242:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang=\"json\">
[
{
\"id\": 9,
\"name\": \"Texas penguins\",
\"team_id\": 9,
\"topic\": \"Progressive fresh-thinking middleware\",
\"members\": [
{ \"id\": 20, \"name\": \"erlinda.grimes\" },
{ \"id\": 21, \"name\": \"lawanda.wilkinson\" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:16:16Z

Aapai: /* Frontend Component */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for \"Assign Grade\" and \"View History\".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

<syntaxhighlight lang="typescript">
import React, { useMemo } from 'react';
import { createColumnHelper } from "@tanstack/react-table";
import Table from "components/Table/Table";
import { useLoaderData } from 'react-router-dom';
import { ITeamRow, TeamSubmission } from './AssignmentUtil';

// Column helper to define typed table columns
const columnHelper = createColumnHelper<ITeamRow>();

const ViewSubmissions: React.FC = () => {
// Fetch data loaded from route loader (assignment teams)
const assignment = useLoaderData() as TeamSubmission[];

// Transform the backend response to a table-friendly structure
const submissions = useMemo<ITeamRow[]>(() =>
assignment.map((team) => ({
id: team.id,
teamName: team.name,
teamMembers: team.members,
historyLink: `/history/${team.team_id}`,
}))
, [assignment]);

// Define the columns used in the table
const columns = useMemo(() => [
columnHelper.accessor('teamName', {
header: 'Team Name',
cell: info => (
<div style={{ color: 'brown', fontWeight: 'bold' }}>
{info.getValue()}
</div>
),
}),
columnHelper.accessor('teamMembers', {
header: 'Team Member(s)',
cell: info => (
<div>
{info.getValue().map((member) => (
<div key={member.id}>
<a href={`/students/${member.id}`} style={{ color: '#b44' }}>
{member.name}
</a>
</div>
))}
</div>
),
}),
columnHelper.display({
id: 'links',
header: 'Links',
cell: ({ row }) => (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<a
href={`/assign_grade/${row.original.id}`}
style={{ color: '#b44', marginBottom: '4px' }}
>
Assign Grade
</a>
<a
href={row.original.historyLink}
style={{ color: '#b44' }}
>
History
</a>
</div>
),
}),
], []);

return (
<div className="mt-4">
<h1 className="text-center">
View Submissions - {assignment[0]?.topic || 'Assignment'}
</h1>

<hr />

{/* Render dynamic table of submissions */}
<Table
data={submissions}
columns={columns}
columnVisibility={{
id: false, // Hide the 'id' column from UI
}}
/>
</div>
);
};

export default ViewSubmissions;
</syntaxhighlight>

* Fetches data with <code>loadAssignmentTeams()</code> via the route's loader
<syntaxhighlight lang="typescript">
// Middleware to fetch teams for assignment
export async function loadAssignmentTeams({ params }: {id:string}) {
let teamsData = [];

if (params.id) {
const response = await axiosClient.get(`/assignments/${params.id}/teams`);
teamsData = response.data;
}

return teamsData;
}
</syntaxhighlight>

* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Members, Assign Grade, and History
* Bootstrap-styled; includes keyboard and screen reader accessibility

=== Backend Controller Code ===
<syntaxhighlight lang=\"ruby\">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: \"Assignment not found\" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.178.127:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang=\"json\">
[
{
\"id\": 9,
\"name\": \"Texas penguins\",
\"team_id\": 9,
\"topic\": \"Progressive fresh-thinking middleware\",
\"members\": [
{ \"id\": 20, \"name\": \"erlinda.grimes\" },
{ \"id\": 21, \"name\": \"lawanda.wilkinson\" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-20T06:10:16Z

Aapai: /* Frontend Implementation */

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== View Submissions Page ==
=== Objective ===
The View Submissions page in Expertiza provides instructors and TAs with a streamlined, responsive interface to evaluate team submissions. This modernized interface includes full backend integration, dynamic UI rendering, accessibility support, and robust error handling.

=== Key Features ===

* '''Fully Integrated with Backend:''' All team data is fetched dynamically using RESTful API.
* '''Responsive UI:''' Layout adapts seamlessly across mobile, tablet, and desktop.
* '''Actionable Buttons:''' Each row includes direct links for \"Assign Grade\" and \"View History\".
* '''Accessibility Features:''' ARIA tags, keyboard navigation, and screen reader support.
* '''Optimized Performance:''' Virtual scrolling and memoization ensure smooth rendering.
* '''Real-Time Synchronization:''' Live data synced with Expertiza backend.

=== Data Structure ===
<syntaxhighlight lang=\"typescript\">
interface ITeamSubmission {
id: number;
teamName: string;
teamMembers: { name: string; id: number }[];
historyLink: string;
topic?: string;
}
</syntaxhighlight>

=== Frontend Component ===

'''Component:''' <code>ViewSubmissions.tsx</code>

* Fetches data with <code>useLoaderData()</code> via the route's loader
* Uses <code>@tanstack/react-table</code> with <code>createColumnHelper</code> for table config
* Displays columns: Team Name, Topic, Members, Assign Grade, History
* Styled with Bootstrap, accessible via keyboard and ARIA roles

=== Backend Controller Code ===
<syntaxhighlight lang=\"ruby\">
def teams
assignment = Assignment.find_by(id: params[:assignment_id])

if assignment.nil?
render json: { error: \"Assignment not found\" }, status: :not_found
return
end

submissions = if assignment.has_teams?
assignment.teams.includes(:teams_users => :user).map do |team|
signed_up_team = team.signed_up_teams.first
topic = signed_up_team&.sign_up_topic&.topic_name

{
id: team.id,
name: team.name,
team_id: team.id,
topic: topic,
members: team.teams_users.map { |tu| { id: tu.user.id, name: tu.user.name } }
}
end
else
assignment.participants.includes(:user).map do |participant|
{
id: participant.id,
name: participant.user.name,
team_id: nil,
topic: nil,
members: [{ id: participant.user.id, name: participant.user.name }]
}
end
end

render json: submissions, status: :ok
end
</syntaxhighlight>

=== API Documentation ===
* '''Endpoint:''' <code>GET /api/v1/assignments/:assignment_id/teams</code>
* '''Returns:''' Array of team info, members, and topic
* '''Swagger Docs:''' [http://152.7.178.127:3002/api-docs/index.html Swagger UI]

=== Sample JSON Response ===
<syntaxhighlight lang=\"json\">
[
{
\"id\": 9,
\"name\": \"Texas penguins\",
\"team_id\": 9,
\"topic\": \"Progressive fresh-thinking middleware\",
\"members\": [
{ \"id\": 20, \"name\": \"erlinda.grimes\" },
{ \"id\": 21, \"name\": \"lawanda.wilkinson\" }
]
}
]
</syntaxhighlight>

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)

2025-04-19T03:28:55Z

Aapai:

== Introduction ==
=== Project Overview ===
This project aims to enhance the grading interface in Expertiza by implementing two key pages:

'''1. View Submissions Page:''' Displays team submissions with resource links and history.

'''2. Assign Grades Page:''' Enables instructors to assign grades and provide comments, integrating peer review data.

The redesigned interface will simplify workflows for instructors and TAs by incorporating real-time API integration, responsive design, and a clear visual hierarchy. The goal is to reduce clutter, improve accessibility, and ensure seamless functionality on all devices.

== Design Goals ==
To ensure a user-friendly, efficient, and maintainable interface, the following design principles are adopted:

* '''Clarity:''' Information should be presented in an easily digestible format. This helps instructors quickly locate relevant data without being overwhelmed by unnecessary details.
* '''Accessibility:''' The interface must comply with WCAG 2.1 standards to ensure usability for all users, including those with disabilities. Features like ARIA roles, keyboard navigation, and proper contrast ratios will be implemented.
* '''Modularity:''' By designing reusable React components (e.g., tables, forms), we adhere to the DRY principle, reducing redundancy and simplifying future updates.
* '''Real-Time Synchronization:''' Instant feedback through API integration ensures that users always work with the latest data. This is critical for grading workflows where delays can cause confusion.
* '''Error Resilience:''' Robust error handling ensures that users receive clear notifications when something goes wrong (e.g., failed API calls or invalid inputs), improving trust in the system.

=== Why These Principles? ===

'''1. Clarity:''' Instructors often deal with large datasets (e.g., multiple teams and submissions). A cluttered interface can slow down their workflow. By focusing on clarity, we aim to streamline their experience and reduce cognitive load.

'''2. Accessibility:''' Accessibility ensures inclusivity. Meeting WCAG standards makes the system usable for everyone, including those relying on assistive technologies like screen readers or keyboard navigation.

'''3. Modularity:''' Modular components reduce development time for future features (e.g., heatgrid integration) and make debugging easier by isolating functionality into smaller units.

'''4. Real-Time Synchronization:''' Grading workflows require up-to-date information to avoid errors (e.g., grading based on outdated peer reviews). Real-time sync ensures data accuracy.

'''5. Error Resilience:''' Instructors need immediate feedback when something goes wrong (e.g., submitting incomplete grades). Clear error messages prevent frustration and guide users toward resolution.

== Current UI Limitations ==
[[File:UI-1.png|900px|center]]

[[File:UI-2.png|900px|center]]
- The current layout is cluttered with overlapping action links.

- No visual distinction between graded and ungraded submissions.

- Missing review indicators are not prominent.

- Tables overflow horizontally on smaller screens.

- Error handling is inconsistent or absent.

== Proposed Implementation ==

=== 1. Optimized View Submissions Table ===
The revamped "View Submissions" table serves as a central hub for instructors to access and evaluate team performance efficiently. It is designed to be responsive, informative, and action-oriented, and is fully integrated with backend APIs to ensure data is always current.

'''Key Features:'''

'''Responsive Design:''' Adapts to mobile, tablet, and desktop screens. Columns collapse intelligently to ensure readability.

'''Team Overview:''' Each row lists the team name, associated members, and their submission topic, all fetched dynamically from the backend.

'''Direct Action Links:''' Provides context-aware links such as "Assign Grade" and "View History" within the table.

'''Visual Feedback:''' Highlights missing or incomplete submissions, allowing instructors to take quick action.

'''Integrated Accessibility:''' Table supports screen readers and keyboard navigation out of the box.

'''Performance Optimized:''' Efficient rendering through virtual scrolling and memoization for large datasets.

'''Backend Integration:''' Data is retrieved via RESTful API endpoints, enabling real-time synchronization with the Expertiza database.

=== 2. Grade Assignment Form ===
The "Assign Grades" page will allow instructors to assign grades and provide comments while integrating peer review data.

Key Features:

- Color-coded alerts for missing reviews.

- Auto-save draft functionality to prevent accidental data loss.

- Rubric-based score suggestions for consistent grading.

=== 3. Error Handling System ===

Error handling is essential to ensure a seamless user experience and system reliability. The error-handling system will address three key areas: '''user input validation''', '''API communication errors''', and '''unexpected system-level failures'''.

'''User Input Validation:'''

- Validates user inputs on the client side to prevent invalid data submissions.

- Ensures required fields (e.g., grades, comments) are completed before submission.

- Provides immediate feedback through visual indicators such as error messages or field highlights.

- Prevents submission until all fields meet validation criteria.

'''API Communication Errors:'''

- Handles network issues, server downtime, or incorrect API responses gracefully.

- Displays contextual error messages (e.g., "Failed to fetch submissions. Please try again later.") to keep users informed.

- Implements retry mechanisms with exponential backoff for transient errors.

- Logs errors for debugging without exposing sensitive information.

'''System-Level Failures:'''

- Catches unexpected rendering errors using error boundaries at the React component level.

- Displays fallback UI with user-friendly messages like "Something went wrong. Please refresh the page."

- Provides options for users to report issues directly to the support team.

=== Key Features ===

* '''Error Classification:''' Errors are categorized into validation, network, and server-side errors for targeted handling.
* '''Error Recovery:''' Users can retry failed actions (e.g., reloading data or resubmitting grades).
* '''User Notifications:''' Immediate feedback is provided via toast messages or modals with actionable suggestions.
* '''Logging and Monitoring:''' Errors are logged for developers to analyze and proactively fix issues.

== Frontend Implementation ==

The frontend implementation focuses on creating a modular, responsive, and accessible interface that integrates seamlessly with backend APIs. It adheres to best practices like separation of concerns, reusability, and responsiveness.

'''State Management:'''

- A centralized state management solution will be used to manage data such as team submissions, grading drafts, and API responses.

- This ensures efficient data sharing across components without unnecessary re-renders.

'''Dynamic Table Rendering:'''

- The "View Submissions" page will feature a responsive table layout that adapts to different screen sizes.

- Columns with lower priority (e.g., team member names) will collapse on smaller screens for better usability.

- Virtual scrolling will be implemented for large datasets to enhance performance.

'''Form Handling on Assign Grades Page:'''

- Includes input fields for grades and comments with real-time validation to ensure data integrity.

- Highlights missing peer reviews visually (e.g., using red icons or badges) so instructors can address them before submitting grades.

'''Responsive Design:'''

- Ensures the interface adapts to various screen sizes using CSS media queries and responsive layouts.

- Implements touch-friendly controls (e.g., larger buttons) for mobile users.

'''Error Handling Integration:'''

- Displays error messages prominently on the UI (e.g., banners or modals) for failed API calls.

- Uses fallback UI for unexpected rendering errors.

'''Reusable Components:'''

- Modular components like tables, forms, and buttons ensure consistency across pages and simplify future maintenance.

- Components follow the Single Responsibility Principle for better testability and scalability.

'''Accessibility Features:'''

- ARIA roles and attributes are added to components for enhanced screen reader support.

- Keyboard navigation is supported for all interactive elements.

- Color contrast ratios meet WCAG standards for readability.

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''

- Solution: The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).

- Functionality: Badges dynamically update based on real-time API data & A filter option allows instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''

- Solution: Missing reviews are highlighted visually on the "Assign Grades" page using red icons or warning messages.

- Functionality: A summary section shows the number of missing reviews per team & Incomplete submissions are flagged automatically during form validation.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''

- Solution: An audit log system records every grade change along with timestamps and user details.

- Functionality: Logs include before/after values of grades and reasons for changes (if provided) & Audit logs are accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''

- Solution: The interface includes larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.

- Functionality: Buttons meet minimum size requirements (48x48px) & Interactive elements are optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''

- Solution: A notification system displays errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").

- Functionality: Notifications appear immediately after an error occurs & Detailed error logs are available in case further troubleshooting is needed.

== Use Case Diagram ==
* Actor: Student
** The student initiates the interaction with the system by clicking on **Grades View** from the main page.
* System Boundary
** Once inside the grading/feedback system, the student can:
*** View Grades for a Given Assignment
**** Allows the student to see the overall grading details for a specific assignment.
**** Redirects to the Stats page.
*** Show Submission
**** Displays the submitted work details for the student’s assignment.
**** Redirects to the Submissions page.
*** Show Reviews
**** Displays the peer or instructor reviews received.
**** Redirects to the Reviews page.
*** Show Author Feedback
**** Shows feedback provided by the author (instructor or peer).
**** Redirects to the Author Feedback page.
*** Teammate Review
**** Allows viewing or giving feedback on teammates’ work.
*** Average / Range
**** For each category (assignment, reviews, feedback), the system can display average scores or range of scores.
*** Back
**** Provides an option to navigate back to the main page or the previous screen.
* Redirect to Main Page
** After the student finishes viewing grades, submissions, reviews, or feedback, they can return to the main page.

[[File:2521 Use Case Diagram.jpeg|750px|center]]

== Test Plan ==
{| class="wikitable"
! Test Case ID !! Test Description !! Expected Outcome !! Priority
|-
| TC001 || Verify that the table displays all team submissions accurately. || All rows and columns should display correct data, including team names, members, and submission links. || High
|-
| TC002 || Validate sorting functionality for columns (e.g., team name, submission date). || Columns should sort correctly in ascending and descending order without data loss or duplication. || Medium
|-
| TC003 || Test responsiveness of the table on different screen sizes (mobile, tablet, desktop). || The table layout should adapt seamlessly to various screen sizes, maintaining usability and readability. || High
|-
| TC004 || Check filtering functionality to display only ungraded submissions. || The filter should accurately show teams with pending grades while hiding graded submissions. || Medium
|-
| TC005 || Verify error handling when API fails to fetch submission data. || A user-friendly error message should be displayed, and the table should show a placeholder or retry option. || High
|-
| TC006 || Validate missing review indicators for teams with incomplete peer reviews. || Teams with missing reviews should display visual indicators (e.g., red icons or badges). || High
|-
| TC007 || Test grade submission functionality with valid inputs. || Grades and comments should be successfully submitted, and the system should display a confirmation message. || High
|-
| TC008 || Validate input field restrictions for grades (e.g., range 0-100). || Inputs outside the allowed range should trigger validation errors and prevent submission. || Medium
|-
| TC009 || Check accessibility features like keyboard navigation and screen reader support. || All interactive elements should be accessible via keyboard, and screen readers should announce table content correctly. || High
|-
| TC010 || Verify performance with large datasets (e.g., 500+ teams). || The table should load within 2 seconds and allow smooth scrolling without lag. || High
|}

=== Test Environment ===
The tests use the following libraries and tools:

* '''Jest:''' JavaScript testing framework
* '''React Testing Library:''' Testing utilities for React components
* '''Jest DOM:''' Custom Jest matchers for asserting on DOM elements
* All tests pass successfully, indicating that the ViewSubmissions and AssignGrade components are functioning as expected.

[[File:testcases.png|900px|center]]

== Performance Metrics ==
The performance metrics aim to ensure the application functions efficiently under various conditions, including large datasets and high user activity. These metrics focus on responsiveness, scalability, and reliability.

{| class="wikitable"
! Metric !! Target !! Description
|-
| Page Load Time || < 1.5 seconds || The "View Submissions" page should load within 1.5 seconds for up to 500 teams on a standard broadband connection.
|-
| Grade Submission Time || < 800 milliseconds || Submitting grades and comments should take less than 800 milliseconds, including API response time.
|-
| Mobile Render Time || < 1 second || The interface should render within 1 second on mobile devices with a 3G connection.
|-
| API Error Recovery || < 3 clicks || Users should be able to recover from API errors (e.g., retry or refresh) within three clicks.
|-
| Large Dataset Handling || Smooth scrolling || The table should support virtual scrolling for datasets with 500+ entries without lag or freezing.
|-
| Missing Review Alerts Rendering Time || < 500 milliseconds || Alerts for missing reviews should appear within 500 milliseconds after loading the "Assign Grades" page.
|-
| Accessibility Compliance || WCAG 2.1 AA || All interactive elements must meet WCAG 2.1 AA standards for accessibility.
|}

== User Stories ==

'''1. As an instructor, I want to see submission status at a glance so that I can quickly assess which teams need grading.'''
* The "View Submissions" page will display submission statuses using color-coded badges (e.g., green for graded, yellow for pending).
* Filtering options will allow instructors to view only ungraded submissions.

'''2. As a TA, I need to identify missing reviews before assigning grades so that I can ensure all reviews are completed.'''
* Missing reviews will be highlighted visually on the "Assign Grades" page using red icons or warning messages.
* A summary section will show the number of missing reviews per team.

'''3. As an admin, I require audit trails for grade changes so that I can track modifications made by instructors or TAs.'''
* An audit log system will record every grade change with timestamps, user details, and reasons for changes (if provided).
* Logs will be accessible via an admin-only interface for review.

'''4. As a mobile user, I need touch-friendly controls so that I can grade submissions easily on my tablet or phone.'''
* The interface will include larger buttons, touch-friendly dropdowns, and swipe gestures where applicable.
* Interactive elements will be optimized for touch input without requiring precision clicks.

'''5. As an instructor, I want error notifications when something goes wrong so that I can take corrective action without delays.'''
* A notification system will display errors as toast messages or modals with actionable suggestions (e.g., "Retry" or "Contact Support").
* Notifications will appear immediately after an error occurs.

'''6. As a TA, I want to sort and filter submissions easily so that I can focus on specific teams or criteria.'''
* Sorting functionality will allow table columns to be organized by team name, submission date, or grading status.
* Filtering options will enable TAs to display submissions based on specific criteria (e.g., ungraded teams).

'''7. As an instructor, I want to assign grades and comments efficiently so that I can complete grading tasks quickly.'''
* Input fields for grades and comments will include real-time validation to ensure data integrity.
* Missing peer reviews will be flagged visually to ensure all required steps are completed before submission.

'''8. As an admin, I want performance reports so that I can monitor system efficiency during peak usage periods.'''
* Performance reports will include metrics like page load times, API response times, and error rates during high user activity.

== Conclusion ==

The redesigned "View Submissions" and "Assign Grades" pages aim to streamline the grading workflow for instructors and TAs while ensuring accessibility, responsiveness, and reliability. By incorporating modular components, real-time API integration, and robust error-handling mechanisms, the system will provide a user-friendly interface that enhances functionality and usability.

Key features such as dynamic table rendering, missing review indicators, and audit trails ensure that grading tasks are efficient and transparent. Additionally, the focus on accessibility and mobile optimization guarantees inclusivity and usability across all devices.

Through adherence to best practices like component reusability, separation of concerns, and performance optimization, this project sets the foundation for future upgrades, including heatgrid integration. The implementation plan aligns with user needs and ensures scalability for handling large datasets without compromising performance.

This project will significantly improve the grading experience within Expertiza by delivering a modern, intuitive, and reliable solution that meets the expectations of instructors, TAs, admins, and mobile users alike.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html

CSC/ECE 517 Spring 2025 - E2520. Reimplement heatgrid UI for reviews

2025-03-25T02:34:21Z

Aapai: /* ✅ Deployment & Testing */

= E2520: Reimplement Heatgrid UI for Reviews =

== 🌟 Introduction ==
The '''Heatgrid UI for Reviews''' is a '''React-based''' component designed to visually represent review scores in a '''structured and user-friendly manner'''. This project enhances usability, data handling, and efficiency while introducing new features to improve the review experience. The component ensures '''seamless interaction and role-based access control''' for different users.

== 🚀 Key Enhancements & Features ==

=== 🎛 1. Toggle Question List ===
* '''Feature:''' Added a '''"Toggle Question List"''' button to display or hide all review questions.
* '''Implementation:''' Users can '''click the button''' to dynamically expand/collapse the list of questions.

Before
[[File:Toggle questions before.png | 1000px]]

After
[[File:Toggle questions after.png | 1000px]]

=== 🏷 2. Hide Tags Button ===
* '''Feature:''' Added a '''"Hide Tags"''' button to toggle the visibility of tags.
* '''Implementation:''' Clicking the button '''hides/shows''' tagging information dynamically.

=== 🎨 3. Color Legend Tooltip ===
* '''Feature:''' Hovering over the color legend displays a tooltip explaining the '''color scale from poor to excellent'''.

[[File:Color legend ss.png| 1000px]]

=== 📌 4. Interaction Legend Tooltip ===
* '''Feature:''' Hovering over the interaction legend now displays a '''tooltip''' with a detailed explanation.

[[File:Interaction legend ss.png| 1000px]]

=== 📝 5. Renamed Comment Categories & Added Word Count Column ===
* '''Feature:''' Changed '''"> 10 Word Comments"''' to '''"Short Comments"''' and '''"> 20 Word Comments"''' to '''"Long Comments"'''. A '''new column''' displays '''word count''' for each review comment.

[[File:HG5 1.png| 1000px]]

[[File:HG5 2.png| 1000px]]

=== 🔼 6. Sorting Questions with Ascending & Descending Arrows ===
* '''Feature:''' Users can now '''sort questions''' using ascending/descending arrows.

[[File:HG6.png| 1000px]]

=== 📊 7. Sort Reviews by Total Score ===
* '''Feature:''' Sort reviews '''in ascending/descending order''' based on '''total review score'''.

[[File:HG7.png| 1000px]]

=== 👥 8. Dynamic Team Members ===
* '''Feature:''' Dynamically '''fetch and display team members' names'''.

[[File:HG8.png|1000px]]

=== 💬 9. Bold & Underlined Comments with Hover Preview ===
* '''Feature:''' Review comments are now '''bold and underlined'''; hovering over them '''shows a preview'''.

[[File:HG9.png| 1000px]]

=== 🔄 10. Refactored Heatgrid to Reusable Components ===
* '''Feature:''' The frontend was '''restructured''' using '''modular, reusable React components'''.

[[File:HeatGridComponent.png|250px]]

=== 🔑 11. Role-Based Access Control ===
* '''Feature:''' Normal users see anonymous "Review 0, Review 1" labels, while '''admins see actual reviewer names'''.

'''🖼 Screenshot:''' ![Role-Based Access](link-to-screenshot)

=== 🖥 12. Backend Integration & Database Configuration ===
* '''Feature:''' Integrated the frontend with the backend, configured the '''database''', and deployed it on '''VCL using Docker'''.

= ✅ Deployment & Testing =

== 🚀 Deployment ==
* '''Deployment Platform:''' Successfully deployed on '''Virtual Computing Lab (VCL)'''.
* '''Deployment Method:''' Used '''Docker''' for containerized setup and consistent environment replication.

== 🧪 Testing ==

=== ✅ Manual Testing ===
Thorough manual testing was conducted for the following features:

* Rendering of '''Summary Report''' and '''Team Information'''
* Display of '''Submission Links'''
* Functionality of the '''Round Selector'''
* Checkbox toggles:
** '''> 10 Word Comments'''
** '''> 20 Word Comments'''
* Conditional rendering of the '''Word Count''' column
* Sorting by:
** '''Row Average'''
** '''Total Review Score''' (ascending/descending toggle)

=== ✅ Automated Testing (`App.test.tsx`) ===
Unit/UI tests written with '''@testing-library/react''' and '''jest'''.

<syntaxhighlight lang="tsx">
import React from "react";
import { render, screen, fireEvent, waitFor } from "@testing-library/react";
import { MemoryRouter, Route, Routes } from "react-router-dom";
import ReviewTable from "./components/ReviewTable"; // Adjust path as needed

describe("ReviewTable page", () => {
const setup = () =>
render(
<MemoryRouter initialEntries={["/view-team-grades"]}>
<Routes>
<Route path="/view-team-grades" element={<ReviewTable />} />
</Routes>
</MemoryRouter>
);

test("renders summary report and team info", async () => {
setup();
expect(screen.getByText(/Summary Report: Program 2/i)).toBeInTheDocument();
expect(screen.getByText(/Team:/i)).toBeInTheDocument();
});

test("renders submission links", async () => {
setup();
expect(
screen.getByText("https://github.ncsu.edu/Program-2-Ruby-on-Rails/WolfEvents")
).toBeInTheDocument();
expect(screen.getByText("README.md")).toBeInTheDocument();
});

test("renders round selector", () => {
setup();
expect(screen.getByText(/Round/i)).toBeInTheDocument();
});

test("renders word count checkboxes", () => {
setup();
expect(screen.getByLabelText(/> 10 Word Comments/i)).toBeInTheDocument();
expect(screen.getByLabelText(/> 20 Word Comments/i)).toBeInTheDocument();
});

test("shows Word Count column when checkbox is selected", async () => {
setup();

expect(screen.queryByText(/Word Count/i)).not.toBeInTheDocument();

const checkbox10 = screen.getByLabelText(/> 10 Word Comments/i);
fireEvent.click(checkbox10);

await waitFor(() => {
expect(screen.getAllByText(/Word Count/i).length).toBeGreaterThan(0);
});
});

test("toggle sort by total score", () => {
setup();
const button = screen.getByText(/Sort by Total Review Score/i);
fireEvent.click(button);
expect(button.textContent).toMatch(/desc|asc/i);
});
});
</syntaxhighlight>

== 🎯 Future Enhancements & Best Practices ==
* Implement automated tests to '''improve maintainability'''.
* Enhance '''responsiveness''' for better mobile support.
* Optimize '''performance''' for larger datasets.
* Follow '''best coding practices''' including '''DRY''' and '''Single Responsibility Principle'''.

== 🏁 Conclusion ==
This project significantly '''enhances the Heatgrid UI''' for reviews, improving '''usability, accessibility, and data handling''' while maintaining an '''intuitive design'''. These newly added features ensure a '''seamless experience''' for students, faculty, and administrators.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html
* '''Link to PR'''
* '''Video of UI/UX Improvements''' https://drive.google.com/file/d/1yLXV0OzHWlY9DPobZYe9JJ7_dUclRLJ4/view?usp=sharing

CSC/ECE 517 Spring 2025 - E2520. Reimplement heatgrid UI for reviews

2025-03-25T02:32:23Z

Aapai: /* ✅ Deployment & Testing */

= E2520: Reimplement Heatgrid UI for Reviews =

== 🌟 Introduction ==
The '''Heatgrid UI for Reviews''' is a '''React-based''' component designed to visually represent review scores in a '''structured and user-friendly manner'''. This project enhances usability, data handling, and efficiency while introducing new features to improve the review experience. The component ensures '''seamless interaction and role-based access control''' for different users.

== 🚀 Key Enhancements & Features ==

=== 🎛 1. Toggle Question List ===
* '''Feature:''' Added a '''"Toggle Question List"''' button to display or hide all review questions.
* '''Implementation:''' Users can '''click the button''' to dynamically expand/collapse the list of questions.

Before
[[File:Toggle questions before.png | 1000px]]

After
[[File:Toggle questions after.png | 1000px]]

=== 🏷 2. Hide Tags Button ===
* '''Feature:''' Added a '''"Hide Tags"''' button to toggle the visibility of tags.
* '''Implementation:''' Clicking the button '''hides/shows''' tagging information dynamically.

=== 🎨 3. Color Legend Tooltip ===
* '''Feature:''' Hovering over the color legend displays a tooltip explaining the '''color scale from poor to excellent'''.

[[File:Color legend ss.png| 1000px]]

=== 📌 4. Interaction Legend Tooltip ===
* '''Feature:''' Hovering over the interaction legend now displays a '''tooltip''' with a detailed explanation.

[[File:Interaction legend ss.png| 1000px]]

=== 📝 5. Renamed Comment Categories & Added Word Count Column ===
* '''Feature:''' Changed '''"> 10 Word Comments"''' to '''"Short Comments"''' and '''"> 20 Word Comments"''' to '''"Long Comments"'''. A '''new column''' displays '''word count''' for each review comment.

[[File:HG5 1.png| 1000px]]

[[File:HG5 2.png| 1000px]]

=== 🔼 6. Sorting Questions with Ascending & Descending Arrows ===
* '''Feature:''' Users can now '''sort questions''' using ascending/descending arrows.

[[File:HG6.png| 1000px]]

=== 📊 7. Sort Reviews by Total Score ===
* '''Feature:''' Sort reviews '''in ascending/descending order''' based on '''total review score'''.

[[File:HG7.png| 1000px]]

=== 👥 8. Dynamic Team Members ===
* '''Feature:''' Dynamically '''fetch and display team members' names'''.

[[File:HG8.png|1000px]]

=== 💬 9. Bold & Underlined Comments with Hover Preview ===
* '''Feature:''' Review comments are now '''bold and underlined'''; hovering over them '''shows a preview'''.

[[File:HG9.png| 1000px]]

=== 🔄 10. Refactored Heatgrid to Reusable Components ===
* '''Feature:''' The frontend was '''restructured''' using '''modular, reusable React components'''.

[[File:HeatGridComponent.png|250px]]

=== 🔑 11. Role-Based Access Control ===
* '''Feature:''' Normal users see anonymous "Review 0, Review 1" labels, while '''admins see actual reviewer names'''.

'''🖼 Screenshot:''' ![Role-Based Access](link-to-screenshot)

=== 🖥 12. Backend Integration & Database Configuration ===
* '''Feature:''' Integrated the frontend with the backend, configured the '''database''', and deployed it on '''VCL using Docker'''.

= ✅ Deployment & Testing =

== 🚀 Deployment ==
* '''Deployment Platform:''' Successfully deployed on '''Virtual Computing Lab (VCL)'''.
* '''Deployment Method:''' Used '''Docker''' for containerized setup and consistent environment replication.

== 🧪 Testing ==

=== ✅ Manual Testing ===
Thorough manual testing was conducted for the following features:

* Rendering of '''Summary Report''' and '''Team Information'''
* Display of '''Submission Links'''
* Functionality of the '''Round Selector'''
* Checkbox toggles:
** '''> 10 Word Comments'''
** '''> 20 Word Comments'''
* Conditional rendering of the '''Word Count''' column
* Sorting by:
** '''Row Average'''
** '''Total Review Score''' (ascending/descending toggle)

=== ✅ Automated Testing (`App.test.tsx`) ===
Unit/UI tests written with '''@testing-library/react''' and '''jest'''.

<syntaxhighlight lang="tsx">
import React from "react";
import { render, screen, fireEvent, waitFor } from "@testing-library/react";
import { MemoryRouter, Route, Routes } from "react-router-dom";
import ReviewTable from "./components/ReviewTable"; // Adjust path as needed

describe("ReviewTable page", () => {
const setup = () =>
render(
<MemoryRouter initialEntries={["/view-team-grades"]}>
<Routes>
<Route path="/view-team-grades" element={<ReviewTable />} />
</Routes>
</MemoryRouter>
);

test("renders summary report and team info", async () => {
setup();
expect(screen.getByText(/Summary Report: Program 2/i)).toBeInTheDocument();
expect(screen.getByText(/Team:/i)).toBeInTheDocument();
});

test("renders submission links", async () => {
setup();
expect(
screen.getByText("https://github.ncsu.edu/Program-2-Ruby-on-Rails/WolfEvents")
).toBeInTheDocument();
expect(screen.getByText("README.md")).toBeInTheDocument();
});

test("renders round selector", () => {
setup();
expect(screen.getByText(/Round/i)).toBeInTheDocument();
});

test("renders word count checkboxes", () => {
setup();
expect(screen.getByLabelText(/> 10 Word Comments/i)).toBeInTheDocument();
expect(screen.getByLabelText(/> 20 Word Comments/i)).toBeInTheDocument();
});

test("shows Word Count column when checkbox is selected", async () => {
setup();

expect(screen.queryByText(/Word Count/i)).not.toBeInTheDocument();

const checkbox10 = screen.getByLabelText(/> 10 Word Comments/i);
fireEvent.click(checkbox10);

await waitFor(() => {
expect(screen.getAllByText(/Word Count/i).length).toBeGreaterThan(0);
});
});

test("toggle sort by total score", () => {
setup();
const button = screen.getByText(/Sort by Total Review Score/i);
fireEvent.click(button);
expect(button.textContent).toMatch(/desc|asc/i);
});
});
</syntaxhighlight>

=== ✅ Route Under Test ===
* '''URL:''' [http://localhost:3000/view-team-grades http://localhost:3000/view-team-grades]
* '''Entry Component:''' <code>ReviewTable.tsx</code>

== 🎯 Future Enhancements & Best Practices ==
* Implement automated tests to '''improve maintainability'''.
* Enhance '''responsiveness''' for better mobile support.
* Optimize '''performance''' for larger datasets.
* Follow '''best coding practices''' including '''DRY''' and '''Single Responsibility Principle'''.

== 🏁 Conclusion ==
This project significantly '''enhances the Heatgrid UI''' for reviews, improving '''usability, accessibility, and data handling''' while maintaining an '''intuitive design'''. These newly added features ensure a '''seamless experience''' for students, faculty, and administrators.

== Team ==

=== Mentor ===
* '''Prathyusha Kodali''' (pkodali@ncsu.edu)

=== Members ===
* '''Raj Patel''' (rbpatel4@ncsu.edu)
* '''Aditya Pai''' (aapai@ncsu.edu)
* '''Parth Kulkarni''' (pnkulka2@ncsu.edu)

== Contributors to this project ==
* '''Raj Patel''' (unityid: rbpatel4, github: Raj-mac24)
* '''Aditya Pai''' (unityid: aapai, github: aditya-pai-nc)
* '''Parth Kulkarni''' (unityid: pnkulka2, github: ParthK7)
* '''Github repo''' https://github.com/aditya-pai-nc/reimplementation-front-end
* '''Backend Hosted on VCL''' http://152.7.178.127:3002/api-docs/index.html
* '''Link to PR'''
* '''Video of UI/UX Improvements'''

CSC/ECE 517 Spring 2025 - E2520. Reimplement heatgrid UI for reviews

2025-03-25T02:28:01Z