Viewing Academic Year

Every year-based screen in the staff hub — the gradebook, enrollment, CBT, payments — shows one school year at a time. Something has to remember which one.

In this app, that something is the URL. The year is a search parameter called campusAcademicYearId, sitting on the campus layout route. So a real URL looks like:

/staff-hub/campus/abc-123/gradebook?campusAcademicYearId=year-456

This page explains that system. Building Year-Scoped Features is what you write on top of it.

Why the URL, and not somewhere else

There were other options — React state in a component, a Zustand store, a value fetched from the server. The URL was chosen because it gives four things at once:

That last point matters most. If the year lived in three places, they could disagree with each other.

The route just carries it

The campus layout route does one job: keep the parameter alive. It never decides what the year should be.

validateSearch: (search) =>
  typeof search.campusAcademicYearId === 'string' && search.campusAcademicYearId !== ''
    ? { campusAcademicYearId: search.campusAcademicYearId }
    : {},
search: {
  middlewares: [retainSearchParams(['campusAcademicYearId'])],
},

validateSearch checks the value is a non-empty string and passes it through. It never supplies a default. retainSearchParams re-adds the parameter as you navigate, so you do not have to pass it in every link.

Two things here look like small details and are not. Both come from real bugs.

The provider keeps it valid

ViewingAcademicYearProvider mounts once, at the campus layout. It is the only code that writes the parameter, and its job is making sure the value is always one that actually exists.

const currentId = campusAcademicYears?.find((cay) => cay.isCurrent)?.id ?? null
const isValid = !!param && !!campusAcademicYears?.some((cay) => cay.id === param)

useEffect(() => {
  if (loadingCampusAcademicYears || !campusAcademicYears) return
  if (isValid) return
  if (currentId) setParam(currentId)
  else if (param) setParam(null)
}, [...])

"Valid" has a deliberately simple definition: the id is one of the years this campus actually has. That single check handles every case:

Notice the last row: when there is no current year, the provider clears the parameter rather than picking something. It never invents a year that does not exist.

What your components receive

{
  campusId: string
  campusAcademicYearId: string | null   // null until resolved, or if no current year
  viewingYear: CampusAcademicYearDto | undefined
  isCurrent: boolean                    // true while still loading, so the ring never flashes
  isUnlocked: boolean                   // is lockedAt empty? this is the write gate
  setCampusAcademicYearId: (id: string) => void
}

isCurrent defaults to true while data is loading. That is deliberate — otherwise the "you are viewing a past year" ring would flash on screen for a moment on every page load.

Two questions, never mix them up

The provider gives you two booleans. They sound similar and mean completely different things.

Because they are independent, all four combinations happen:

• Current and unlocked — the normal case. No ring, everything editable.
• Current but locked — the school sealed this year. No ring, but everything is read-only.
• Past and unlocked — a teacher finishing last year's marks. Ring shows, but writes still work.
• Past and locked — ring shows, everything read-only.

A short way to remember it: the ring tells you where you are; the lock tells you what you may change.

This matches the server exactly. The API's assertNotLocked checks lockedAt and nothing else — see Academic-Year Scoping.

Where each piece lives

Where to go next