# 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, module navigation, global search,
  user display, and logout link.
- Any `.jspf` fragment that contains user-visible Simplified Chinese text must
  declare `<%@ page pageEncoding="UTF-8" %>` at the top. Do not rely only on the
  including JSP page or response `Content-Type`; Tomcat/Jasper can otherwise
  compile the fragment with a non-UTF-8 default and render mojibake.
- JSP-rendered HTML responses must be served as `text/html;charset=UTF-8` by
  the encoding filter or the JSP page directive. Request/response character
  encoding alone is not enough for browsers to decode Simplified Chinese safely.
- 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'`.
- For active navigation in forwarded JSPs, derive the current location from the
  public Servlet path before falling back to the JSP servlet path. Use exact
  matches or slash-delimited prefixes; do not use broad `fn:contains` checks
  against `requestURI`, because forwarded pages expose `/WEB-INF/jsp/...` paths
  and can activate unrelated sidebar items.

  ```jsp
  <c:set var="currentPath" value="${requestScope['javax.servlet.forward.servlet_path']}" />
  <c:if test="${empty currentPath}">
      <c:set var="currentPath" value="${pageContext.request.servletPath}" />
  </c:if>
  <a class="${(currentPath == '/books' or fn:startsWith(currentPath, '/books/')) ? 'is-active' : ''}">
  ```
- 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.