Listings

Overview

Listings are the backbone of data-driven features in the platform. They provide a unified pattern for displaying, searching, filtering, creating, editing, and deleting records—all with a consistent UX and optimistic updates.

Every listing follows the same structure, making it predictable for developers and consistent for users. Whether you're working with Students, Teachers, Classes, Events, or any other entity—the pattern remains the same.

Key Features

---

Listing Structure

Every listing follows the mirror pattern — the URL route produces two directories: one in app/ for routing, one in components/ for feature logic. Replace abc with your feature name.

---

Standardized File Patterns

Each listing directory follows these naming conventions:

---

Page Layout Composition

┌─────────────────────────────────────────────────────────────────┐
│  PageTitle                     src/components/atom/page-title.tsx│
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ Abc Management                                              ││
│  │ Manage all abc records in your school                       ││
│  └─────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────┤
│  PageNav                         src/components/atom/page-nav.tsx│
│  ┌──────────┬──────────┬──────────┬──────────┐                  │
│  │ All      │ Active   │ Archive  │ Settings │                  │
│  └──────────┴──────────┴──────────┴──────────┘                  │
├─────────────────────────────────────────────────────────────────┤
│  Toolbar                         src/components/atom/toolbar.tsx │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ SearchInput    Filters           ViewToggle Export Create   ││
│  │ [🔍 Search...] [Status▾][Type▾]  [≡/⊞]     [↓]    [+]      ││
│  └─────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────┤
│  DataTable                   src/components/table/data-table.tsx │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ ☐ │ Name        │ Status   │ Created    │ Actions          ││
│  │───┼─────────────┼──────────┼────────────┼──────────────────││
│  │ ☐ │ Item 1      │ Active   │ 2025-01-20 │ [···]            ││
│  │ ☐ │ Item 2      │ Draft    │ 2025-01-19 │ [···]            ││
│  └─────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────┤
│  OR GridContainer          src/components/atom/grid-container.tsx│
│  ┌─────────┐ ┌─────────┐ ┌─────────┐                            │
│  │ Card 1  │ │ Card 2  │ │ Card 3  │                            │
│  └─────────┘ └─────────┘ └─────────┘                            │
├─────────────────────────────────────────────────────────────────┤
│  Modal (when open)              src/components/atom/modal/modal  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ ModalFormLayout  src/components/atom/modal/modal-form-layout ││
│  │ ┌──────────────┐  ┌───────────────────────────────────────┐││
│  │ │ Create Abc   │  │  Form (listings/abc/form.tsx)         │││
│  │ │ Add new item │  │  - Field 1                           │││
│  │ └──────────────┘  └───────────────────────────────────────┘││
│  │ ModalFooter      src/components/atom/modal/modal-footer     ││
│  │ [━━━━━━━━━━━━━━━━━━━━━━━━━━━━]                              ││
│  │ Step 1 of 2: Basic Info              [Cancel] [Next]       ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

---

Component Flow

Route (page.tsx)
    │
    ▼
Content (content.tsx) ──── Server Component
    │ • getTenantContext()
    │ • Parse URL params
    │ • Fetch data via queries.ts
    │
    ▼
Table (table.tsx) ──────── Client Component
    │ • useModal()
    │ • usePlatformView()
    │ • useDataTable()
    │
    ├──► Toolbar
    │      • SearchInput
    │      • ViewToggle
    │      • ExportButton
    │      • CreateButton
    │
    ├──► DataTable / GridContainer
    │      • Columns (columns.tsx)
    │      • Row actions
    │      • Pagination
    │
    └──► Modal
           • Form (form.tsx)
           • ModalFormLayout
           • ModalFooter

---

Reference Implementation

The Grades module serves as the reference implementation with the complete pattern:

---

Core Hooks

---

Modules Status

✅ = Complete | 🔄 = Using pattern, needs queries.ts/authorization.ts

---

Best Practices

Multi-Tenant Safety

• ALWAYS include schoolId in every database query
• Get schoolId from session: const { schoolId } = session.user
• Missing schoolId breaks tenant isolation

Column Definitions

• Define handlers BEFORE columns useMemo
• Columns with hooks (useModal) must be generated in client components
• Pass callbacks via getColumns(dictionary, lang, { onDelete, onEdit, onView })

Optimistic Updates

• Call optimisticRemove(id) before server request
• Call refresh() on error to rollback
• Use optimisticUpdate(id, updater) for in-place updates

Server Actions

• Start with "use server" directive
• Validate with Zod on both client (UX) and server (security)
• Call revalidatePath() or redirect() after mutations
• Return typed ActionResponse<T> results

Modal Forms

• Use ModalFormLayout for two-column header/form layout
• Use ModalFooter for progress bar and navigation
• Call onSuccess() callback after successful mutations

---

Listing Maturity Levels

---

The Listings pattern ensures consistency across all data-driven features. By following this pattern, you get auto-refresh, optimistic updates, view toggles, and export functionality—all with type-safe queries and role-based authorization.