# Component Guidelines

> JSP fragment, form, table, and reusable UI conventions.

---

## Overview

This project uses JSP-based presentation, not a component framework. Treat JSP
includes, fragments, tag files, form layouts, tables, and shared CSS classes as
the reusable UI units.

---

## JSP Includes And Fragments

- Use shared fragments for repeated layout pieces such as header, navigation,
  sidebar, footer, pagination, and message banners.
- Use `.jspf` includes for the current JSP presentation layer. The authenticated
  application frame lives in `src/main/webapp/WEB-INF/jsp/common/header.jspf`
  and owns the dark sidebar, top utility bar, role workbench links, module
  navigation, global search, user display, and logout link.
- Preserve role-conditioned navigation in that shared frame: administrator-only
  links stay inside `sessionScope.userRole == 'administrator'`; staff links stay
  inside `administrator or librarian`; reader-only links stay inside
  `sessionScope.userRole == 'reader'`.
- Keep fragments presentation-focused. They should not open database
  connections or call DAOs.

---

## Interface Copy

- Render user-visible JSP copy in Simplified Chinese, including navigation,
  headings, form labels, buttons, table headers, empty states, and accessible
  labels.
- Keep machine-readable values unchanged: URLs, request parameter names, CSS
  classes, Java identifiers, enum codes, database values, and servlet names stay
  in their existing code form.
- Translate display helper output and controller/service messages when they are
  rendered into JSP pages.

---

## Forms

- Forms should post to Servlet controller endpoints, not directly to DAOs or
  JSP-only handlers.
- Render validation messages from request attributes set by controllers.
- Preserve user-entered values on validation failure where practical.
- Use clear labels, required-field indicators, and server-side validation for
  book, reader, borrowing, login, and permission forms.

---

## Tables And Reports

- Use consistent table patterns for book lists, reader lists, borrowing
  records, rankings, inventory reports, overdue reports, and system logs.
- Include stable empty states and pagination or filtering controls when lists
  can grow.
- Keep search forms aligned with supported filters: title, author, category,
  and book ID.

---

## Styling

Implement JSP/CSS pages to faithfully restore the approved image design. Prefer
semantic class names tied to page structure or reusable UI roles. Avoid adding a
frontend component framework unless explicitly introduced later.