commit

docs/announcement-list-table-redesign.md

@@ -0,0 +1,87 @@
+# Announcement List Table Redesign
+
+## Existing Structure Review
+
+- Reused the existing `announcements` feature and kept the same route-handler, React Query, permission, and workflow stack.
+- Reused the shared table stack:
+  - `DataTable`
+  - `useDataTable`
+  - `DataTableColumnHeader`
+  - `DataTableFacetedFilter`
+  - `DataTableViewOptions`
+- Reused the current announcement state transitions, pin/unpin endpoints, audit logging, and pagination flow.
+- Replaced only the presentation layer of the list page from cards to an enterprise-style data table.
+
+## Files Changed
+
+- `src/features/announcements/api/types.ts`
+- `src/features/announcements/api/service.ts`
+- `src/features/announcements/components/announcements-listing.tsx`
+- `src/features/announcements/components/announcements-page.tsx`
+- `src/features/announcements/components/announcement-columns.tsx`
+- `src/features/announcements/components/announcement-toolbar.tsx`
+- `src/features/announcements/components/announcement-action-menu.tsx`
+- `src/features/announcements/server/announcement-data.ts`
+- `src/app/api/announcements/route.ts`
+
+## UI Before / After
+
+- Before: announcement rows were rendered as stacked cards with inline action buttons.
+- After: the page uses a structured data table with fixed columns, sortable headers, row selection, and a per-row dropdown action menu.
+- Search and filter controls were kept but moved into a table-friendly toolbar layout.
+- Pinned status is now visible in a dedicated pin column instead of only inside the card header.
+
+## Table Columns
+
+- Selection checkbox
+- Pin indicator
+- Announcement title with content preview
+- Status badge
+- Published date
+- End date
+- Creator
+- Attachment
+- Action menu
+
+## Action Menu
+
+- Replaced inline buttons with a dropdown menu per row.
+- Menu entries still depend on the same permission and workflow checks:
+  - View
+  - Edit
+  - Submit
+  - Approve
+  - Return
+  - Reject
+  - Publish
+  - Pin / Unpin
+  - Archive
+  - Delete
+- Review and delete actions still reuse the existing dialogs.
+
+## Responsive Result
+
+- The toolbar stacks vertically on smaller widths and expands horizontally on larger screens.
+- The table stays inside the shared horizontal scroll container instead of overflowing the page.
+- The actions column remains pinned to the right for easier management on wide datasets.
+
+## Performance Impact
+
+- Kept the existing server pagination and React Query cache path.
+- Added sorting as an additive query parameter without changing the response shape.
+- Preserved the existing pinned-first ordering behavior, then applied requested table sorting.
+- No duplicate fetch path or alternate data source was introduced.
+
+## Regression Check
+
+- Search still uses the existing announcement query path.
+- Status and pin filters still work through the same list endpoint.
+- Pagination behavior is unchanged.
+- Workflow actions still call the same mutation and pin/unpin endpoints.
+- Permission checks remain enforced both in UI behavior and server routes.
+
+## Future Improvements
+
+- Add real bulk actions once the backend supports batch publish/archive/delete/pin operations.
+- Add optional mobile card mode if the product team wants a more touch-optimized small-screen presentation.
+- Add richer filter dimensions such as creator or year if the backend exposes options for them.