create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/features/courses/portal/ui/catalogue.tsx

@@ -0,0 +1,86 @@
+// The portal's catalogue: the courses on offer as cards, searched by title and summary and narrowed by tag, each
+// card opening the course's page.
+import { useState } from 'react'
+import { Search } from 'lucide-react'
+import { useQuery } from '@tanstack/react-query'
+import { useClient, useLocale, useScreen } from 'mithaq/admin/react'
+import { Input } from '@/components/ui/input'
+import { Toggle } from '@/components/ui/toggle'
+import { PortalShell, display } from './shell.tsx'
+import { CardsLoading, CourseCard, ReadFailed } from './parts.tsx'
+import { inLocale } from './rules.ts'
+import { catalogueOf } from './reads.ts'
+
+/** Drawn whole as the courses' list page, so it reads the list itself. */
+export function Catalogue() {
+  const { locale, t } = useLocale()
+  const client = useClient()
+  const screen = useScreen()
+  const read = useQuery({ queryKey: ['portal-catalogue'], queryFn: () => catalogueOf({ client, maxLimit: screen.maxLimit, now: Date.now() }), staleTime: 30_000 })
+  const [term, setTerm] = useState('')
+  const [tag, setTag] = useState<string>()
+  const found = read.data
+  const asked = term.trim().toLocaleLowerCase(locale)
+  const shown = found?.courses.filter((course) =>
+    (!tag || (Array.isArray(course.tags) && course.tags.includes(tag)))
+    && (!asked || [course.title, course.summary].some((one) => typeof one === 'string' && one.toLocaleLowerCase(locale).includes(asked))))
+  const title = t('courses.plural', 'Courses')
+  return (
+    <PortalShell
+      regions={{
+        header: <h1 className={`${display} text-3xl`}>{title}</h1>,
+        main: (
+          <div className="grid gap-5">
+            <div className="grid gap-3">
+              <label className="border-input bg-card focus-within:ring-ring flex h-12 items-center gap-2.5 rounded-full border px-4 focus-within:ring-2">
+                <Search aria-hidden className="text-muted-foreground size-4.5 shrink-0" />
+                <span className="sr-only">{t('portal.search', 'Search courses')}</span>
+                <Input
+                  type="search"
+                  value={term}
+                  onChange={(event) => setTerm(event.target.value)}
+                  placeholder={t('portal.search', 'Search courses')}
+                  className="h-auto border-0 bg-transparent p-0 text-[15px] shadow-none focus-visible:ring-0 dark:bg-transparent"
+                />
+              </label>
+              {found?.tags.size ? (
+                <div role="group" aria-label={t('portal.byTag', 'Filter by tag')} className="flex flex-wrap gap-2">
+                  <Toggle variant="outline" pressed={!tag} onPressedChange={() => setTag(undefined)} className="aria-pressed:bg-foreground aria-pressed:text-background h-11 rounded-full px-4">
+                    {t('portal.allTags', 'All')}
+                  </Toggle>
+                  {[...found.tags.values()].map((one) => (
+                    <Toggle
+                      key={String(one.id)}
+                      variant="outline"
+                      pressed={tag === one.id}
+                      onPressedChange={(pressed) => setTag(pressed ? String(one.id) : undefined)}
+                      className="aria-pressed:bg-foreground aria-pressed:text-background h-11 rounded-full px-4"
+                    >
+                      {inLocale(one.name, locale)}
+                    </Toggle>
+                  ))}
+                </div>
+              ) : null}
+            </div>
+            {read.isError ? <ReadFailed retry={() => void read.refetch()} /> : !found || !shown ? <CardsLoading /> : shown.length ? (
+              <div className="grid grid-cols-[repeat(auto-fill,minmax(16rem,1fr))] gap-5">
+                {shown.map((course) => (
+                  <CourseCard
+                    key={String(course.id)}
+                    course={course}
+                    cover={found.covers.get(String(course.cover))}
+                    next={found.next.get(String(course.id))}
+                    tags={found.tags}
+                    href={`${screen.path}/courses/${encodeURIComponent(String(course.id))}`}
+                  />
+                ))}
+              </div>
+            ) : (
+              <p className="text-muted-foreground text-sm">{found.courses.length ? t('portal.noMatch', 'No course matches.') : t('courses.noneOnOffer', 'No courses on offer yet.')}</p>
+            )}
+          </div>
+        ),
+      }}
+    />
+  )
+}

package/template/templates/features/courses/portal/ui/course.tsx

@@ -0,0 +1,176 @@
+// A course's page in the portal: its cover, what it is and costs, what it covers, and its sessions still to come.
+// Where the course lets its students enroll themselves, a student picks a session with a seat left and takes it;
+// where it does not, the page says the school enrolls them. Who may take a seat, and whether one is left, the
+// server decides: this page only offers what it would admit.
+import { useState } from 'react'
+import { ArrowLeft, CalendarDays, MapPin } from 'lucide-react'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import type { Row } from 'mithaq/admin'
+import { holds } from 'mithaq/admin'
+import { useAccess, useClient, useLocale, useRecord, useScreen, useUser } from 'mithaq/admin/react'
+import { RichTextValueView } from 'mithaq-admin/rich-text-viewer.tsx'
+import { refusalKeyOf } from 'mithaq-admin/refusal.ts'
+import { toast } from 'mithaq-admin/toast.tsx'
+import { Button } from '@/components/ui/button'
+import { DirectionalIcon } from '@/components/ui/directional-icon'
+import { Skeleton } from '@/components/ui/skeleton'
+import { PortalShell, display } from './shell.tsx'
+import { Cover, Tags, useOption, usePlace } from './parts.tsx'
+import { feeOf, seatsOf, whenOf } from './rules.ts'
+import { byIds, readSeats } from './reads.ts'
+
+type Session = Row & { seatsLeft?: number | null }
+
+export function Course() {
+  const { locale, t } = useLocale()
+  const client = useClient()
+  const screen = useScreen()
+  const access = useAccess()
+  const user = useUser()
+  const record = useRecord()
+  const option = useOption()
+  const place = usePlace()
+  const queries = useQueryClient()
+  const id = String(record?.id ?? '')
+  // The course with its sessions and the seats each has left, which a student, who reads its own seats alone,
+  // could not count; then its cover and tags, and the viewer's own seats in it.
+  const read = useQuery({
+    queryKey: ['portal-course', id],
+    queryFn: async () => {
+      const course = (await client({ kayan: 'courses', operation: 'findWithSessions', input: { id } })) as Row & { sessions: Session[] }
+      const [covers, tags, mine] = await Promise.all([
+        byIds({ client, maxLimit: screen.maxLimit, kayan: 'media', ids: typeof course.cover === 'string' ? [course.cover] : [] }),
+        byIds({ client, maxLimit: screen.maxLimit, kayan: 'tags', ids: Array.isArray(course.tags) ? course.tags.map(String) : [] }),
+        user.id && course.sessions.length ? readSeats({ client, maxLimit: screen.maxLimit, where: { and: [{ student: { equals: user.id } }, { session: { in: course.sessions.map((one) => one.id) } }] } }) : [],
+      ])
+      return { course, cover: covers.get(String(course.cover)), tags, mine }
+    },
+    enabled: !!id,
+  })
+  const [picked, setPicked] = useState<string>()
+  const [busy, setBusy] = useState(false)
+  const course = read.data?.course ?? record ?? {}
+  const now = Date.now()
+  // A session still to come and open; one archived takes no seat, so it is not offered.
+  const sessions = (course.archived === true ? [] : read.data?.course.sessions ?? [])
+    .filter((one) => one.archived !== true && new Date(one.startsAt as string).getTime() > now)
+    .sort((a, b) => new Date(a.startsAt as string).getTime() - new Date(b.startsAt as string).getTime())
+  // The viewer's own seat in a session of this course still to come, which it already holds.
+  const held = read.data?.mine.find((one) => new Date(one.startsAt as string).getTime() > now)
+  // A student takes its own seat; whoever reads every seat enrolls others from the enrollments' own page.
+  const self = holds(access, 'enrollments.create') && !holds(access, 'enrollments.others')
+  // Whoever runs the catalogue reads an archived course too; the portal offers none of its seats.
+  const open = course.selfEnroll === true && course.archived !== true
+  const chosen = sessions.find((one) => one.id === picked && one.seatsLeft !== 0)
+  const fee = feeOf({ fee: course.fee, currency: course.currency, locale, t })
+  const enroll = async () => {
+    if (!chosen) return
+    setBusy(true)
+    try {
+      await client({ kayan: 'enrollments', operation: 'create', input: { session: chosen.id } })
+      toast.success(t('portal.enrolled', 'You are enrolled.')!)
+      await queries.invalidateQueries()
+    } catch (thrown) {
+      const key = refusalKeyOf(thrown)
+      toast.error((key && t(key)) || t('portal.enrollFailed', 'The seat was not taken. Please try again.')!)
+      await queries.invalidateQueries({ queryKey: ['portal-course', id] })
+    } finally {
+      setBusy(false)
+    }
+  }
+  const list = `${screen.path}/courses`
+  return (
+    <PortalShell
+      regions={{
+        header: (
+          <div className="grid gap-5">
+            <div className="relative -mx-4 overflow-hidden sm:mx-0 sm:rounded-3xl">
+              <Cover course={course} cover={read.data?.cover} className="h-56 w-full sm:h-72" />
+              <a href={list} aria-label={t('portal.back', 'Back to courses')} className="bg-card text-foreground focus-visible:ring-ring absolute start-4 top-4 grid size-11 place-items-center rounded-full shadow focus-visible:ring-2 focus-visible:outline-none">
+                <DirectionalIcon><ArrowLeft aria-hidden className="size-5" /></DirectionalIcon>
+              </a>
+            </div>
+            <div className="grid gap-2.5">
+              {read.data ? <Tags course={course} tags={read.data.tags} /> : null}
+              <h1 className={`${display} text-3xl leading-tight`}>{String(course.title ?? '')}</h1>
+              <p className="text-muted-foreground flex flex-wrap gap-x-4 gap-y-1 text-sm">
+                {fee ? <span><bdi>{fee}</bdi> {course.fee ? t('portal.perSeat', 'per seat') : null}</span> : null}
+                {option('courses', 'delivery', course.delivery) ? <span>{option('courses', 'delivery', course.delivery)}</span> : null}
+              </p>
+            </div>
+          </div>
+        ),
+        main: (
+          <div className="grid gap-8 pb-24 md:grid-cols-[minmax(0,3fr)_minmax(0,2fr)] md:pb-0">
+            <section aria-labelledby="about" className="grid content-start gap-3">
+              <h2 id="about" className="text-lg font-semibold">{t('portal.aboutCourse', 'About this course')}</h2>
+              {typeof course.summary === 'string' && course.summary ? <p className="leading-relaxed">{course.summary}</p> : null}
+              {course.details ? <RichTextValueView value={course.details} t={t} /> : null}
+            </section>
+            <section aria-labelledby="sessions" className="grid content-start gap-3">
+              <h2 id="sessions" className="text-lg font-semibold">{self && open && !held ? t('portal.choose', 'Choose a session') : t('sessions.plural', 'Sessions')}</h2>
+              {!read.data && !read.isError ? <Skeleton className="h-20 rounded-2xl" /> : null}
+              {read.data && !sessions.length ? <p className="text-muted-foreground text-sm">{t('portal.noSession', 'No session scheduled yet')}</p> : null}
+              {self && open && !held ? (
+                <div role="radiogroup" aria-labelledby="sessions" className="grid gap-2.5">
+                  {sessions.map((one) => {
+                    const full = one.seatsLeft === 0
+                    return (
+                      <label key={String(one.id)} className={`bg-card flex items-center gap-3 rounded-2xl border-2 px-4 py-3.5 ${picked === one.id ? 'border-primary' : 'border-transparent'} ${full ? 'opacity-60' : 'cursor-pointer'}`}>
+                        <input type="radio" name="session" value={String(one.id)} disabled={full} checked={picked === one.id} onChange={() => setPicked(String(one.id))} className="accent-primary size-5" />
+                        <SessionLine session={one} place={place(one)} />
+                        <span className={`shrink-0 text-sm ${full ? 'text-muted-foreground' : 'text-primary'}`}>{seatsOf({ seatsLeft: one.seatsLeft, locale, t })}</span>
+                      </label>
+                    )
+                  })}
+                </div>
+              ) : (
+                <ul className="grid gap-2.5">
+                  {sessions.map((one) => (
+                    <li key={String(one.id)} className="bg-card flex items-center gap-3 rounded-2xl px-4 py-3.5">
+                      <SessionLine session={one} place={place(one)} />
+                      <span className="text-muted-foreground shrink-0 text-sm">{seatsOf({ seatsLeft: one.seatsLeft, locale, t })}</span>
+                    </li>
+                  ))}
+                </ul>
+              )}
+              {self && open && !held && sessions.length ? (
+                // At the foot of a phone, over the tab bar, so the button stays in reach; in the flow from md up.
+                <div className="bg-card fixed inset-x-0 bottom-[calc(4.25rem+max(env(safe-area-inset-bottom),0.75rem))] z-10 flex items-center gap-3 border-t px-4 py-3 md:static md:rounded-2xl md:border">
+                  {fee ? (
+                    <span className="grid shrink-0">
+                      <span className="text-muted-foreground text-xs">{t('portal.total', 'Total')}</span>
+                      <span className="text-lg font-semibold"><bdi>{fee}</bdi></span>
+                    </span>
+                  ) : null}
+                  <Button type="button" size="lg" className="h-12 flex-1 rounded-full text-base" disabled={!chosen || busy} onClick={() => void enroll()}>
+                    {chosen ? t('portal.enrollIn', 'Enroll on {when}')!.replace('{when}', () => whenOf({ value: chosen.startsAt, locale }) ?? '') : t('portal.pick', 'Pick a session')}
+                  </Button>
+                </div>
+              ) : null}
+              {held ? (
+                <p className="bg-accent text-accent-foreground rounded-2xl px-4 py-3 text-sm">
+                  {t('portal.holding', 'You hold a seat on {when}.')!.replace('{when}', () => whenOf({ value: held.startsAt, locale }) ?? '')}{' '}
+                  <a href={`${screen.path}/enrollments`} className="font-semibold underline-offset-4 hover:underline">{t('portal.myEnrollments', 'My enrollments')}</a>
+                </p>
+              ) : self && !open && read.data ? (
+                <p className="bg-accent text-accent-foreground rounded-2xl px-4 py-3 text-sm">{t('portal.askSchool', 'Ask your school to enroll you.')}</p>
+              ) : null}
+            </section>
+          </div>
+        ),
+      }}
+    />
+  )
+}
+
+/** A session as a line: when it meets, and where and how. */
+function SessionLine({ session, place }: { session: Row; place: string }) {
+  const { locale } = useLocale()
+  return (
+    <span className="grid min-w-0 flex-1 gap-0.5">
+      <span className="flex items-center gap-1.5 font-semibold"><CalendarDays aria-hidden className="size-4 shrink-0" /><span>{whenOf({ value: session.startsAt, locale })}</span></span>
+      {place ? <span className="text-muted-foreground flex items-center gap-1.5 text-sm"><MapPin aria-hidden className="size-4 shrink-0" />{place}</span> : null}
+    </span>
+  )
+}

package/template/templates/features/courses/portal/ui/enrollments.tsx

@@ -0,0 +1,170 @@
+// The portal's enrollments, upcoming first. A student reads its own seats as cards: the course's title and cover,
+// when the session meets, where and how, and, before it starts, the way to give the seat back. Whoever reads every
+// seat, an instructor, reads them as a table with each seat's student, named only where the server lets it read
+// that person.
+import { useState } from 'react'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { holds } from 'mithaq/admin'
+import { useAccess, useClient, useLocale, useScreen } from 'mithaq/admin/react'
+import { refusalKeyOf } from 'mithaq-admin/refusal.ts'
+import { toast } from 'mithaq-admin/toast.tsx'
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle } from '@/components/ui/alert-dialog'
+import { Button, buttonVariants } from '@/components/ui/button'
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table'
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs'
+import { PortalShell, display } from './shell.tsx'
+import { CardsLoading, Cover, ReadFailed, usePlace } from './parts.tsx'
+import { byWhen, startsIn, whenOf } from './rules.ts'
+import { readSeats, type Seat } from './reads.ts'
+
+export function Enrollments() {
+  const { t } = useLocale()
+  const client = useClient()
+  const screen = useScreen()
+  const access = useAccess()
+  const others = holds(access, 'enrollments.others')
+  // A student is never asked for people, whom it reads none of.
+  const people = others && access.collections?.enrollments?.fields?.student?.read === true
+  const read = useQuery({ queryKey: ['portal-enrollments', people], queryFn: () => readSeats({ client, maxLimit: screen.maxLimit, people }) })
+  const [when, setWhen] = useState<'upcoming' | 'past'>('upcoming')
+  const now = Date.now()
+  const split = read.data && byWhen(read.data, now)
+  const shown = split?.[when] ?? []
+  const title = others ? t('enrollments.plural', 'Enrollments') : t('portal.myEnrollments', 'My enrollments')
+  const creates = others && holds(access, 'enrollments.create')
+  return (
+    <PortalShell
+      regions={{
+        header: (
+          <div className="flex flex-wrap items-center justify-between gap-3">
+            <h1 className={`${display} text-3xl`}>{title}</h1>
+            {creates ? <a href={`${screen.path}/enrollments/new`} className={buttonVariants({ className: 'h-11 rounded-full px-5' })}>{t('enrollments.new', 'New enrollment')}</a> : null}
+          </div>
+        ),
+        main: (
+          <div className="grid gap-5">
+            <Tabs value={when} onValueChange={(value) => setWhen(value as 'upcoming' | 'past')}>
+              <TabsList className="h-11 w-full max-w-sm">
+                <TabsTrigger value="upcoming" className="h-9 flex-1">{t('portal.upcoming', 'Upcoming')}</TabsTrigger>
+                <TabsTrigger value="past" className="h-9 flex-1">{t('portal.past', 'Past')}</TabsTrigger>
+              </TabsList>
+            </Tabs>
+            {read.isError ? <ReadFailed retry={() => void read.refetch()} /> : !split ? <CardsLoading count={2} /> : !shown.length ? (
+              <p className="text-muted-foreground text-sm">{when === 'upcoming' ? t('portal.noneUpcoming', 'No session to come.') : t('portal.nonePast', 'No past session.')}</p>
+            ) : others ? (
+              <SeatTable seats={shown} people={people} />
+            ) : (
+              <ul className="grid gap-3.5">
+                {shown.map((one, at) => <SeatCard key={String(one.seat.id)} seat={one} first={when === 'upcoming' && at === 0} now={now} canLeave={when === 'upcoming' && holds(access, 'enrollments.delete')} />)}
+              </ul>
+            )}
+          </div>
+        ),
+      }}
+    />
+  )
+}
+
+/** One seat of the viewer's own as a card, the soonest one marked. */
+function SeatCard({ seat, first, now, canLeave }: { seat: Seat; first: boolean; now: number; canLeave: boolean }) {
+  const { locale, t } = useLocale()
+  const screen = useScreen()
+  const place = usePlace()
+  const soon = startsIn({ value: seat.startsAt, now, locale })
+  const where = place(seat.session)
+  return (
+    <li className="bg-card overflow-hidden rounded-2xl">
+      <div className="flex gap-3.5 p-4">
+        <Cover course={seat.course} cover={seat.cover} className="size-18 shrink-0 rounded-xl" />
+        <div className="grid min-w-0 content-start gap-1">
+          <h2 className="text-[17px] leading-snug font-semibold">{String(seat.course?.title ?? t('admin.notAvailable', 'Not available'))}</h2>
+          <p className="text-sm">{whenOf({ value: seat.startsAt, locale })}</p>
+          {where ? <p className="text-muted-foreground text-sm">{where}</p> : null}
+        </div>
+      </div>
+      <div className={`flex flex-wrap items-center justify-between gap-3 px-4 py-3 ${first ? 'bg-accent' : 'border-t'}`}>
+        <span className={`text-sm ${first ? 'text-accent-foreground font-semibold' : 'text-muted-foreground'}`}>{soon ? t('portal.startsIn', 'Starts {when}')!.replace('{when}', () => soon) : null}</span>
+        <div className="flex gap-2">
+          {canLeave ? <Leave seat={seat} /> : null}
+          {seat.course ? (
+            <a href={`${screen.path}/courses/${encodeURIComponent(String(seat.course.id))}`} className={buttonVariants({ className: 'h-11 rounded-full px-4' })}>{t('portal.course', 'Course')}</a>
+          ) : null}
+        </div>
+      </div>
+    </li>
+  )
+}
+
+/** Gives a seat back before its session starts, behind a question, since the seat goes to whoever takes it next. */
+function Leave({ seat }: { seat: Seat }) {
+  const { t } = useLocale()
+  const client = useClient()
+  const queries = useQueryClient()
+  const [asking, setAsking] = useState(false)
+  const leave = async () => {
+    try {
+      await client({ kayan: 'enrollments', operation: 'delete', input: { id: seat.seat.id } })
+      toast.success(t('portal.left', 'Your enrollment is cancelled.')!)
+    } catch (thrown) {
+      const key = refusalKeyOf(thrown)
+      toast.error((key && t(key)) || t('portal.leaveFailed', 'The enrollment was not cancelled. Please try again.')!)
+    }
+    await queries.invalidateQueries()
+  }
+  return (
+    <>
+      <Button type="button" variant="ghost" className="text-destructive h-11 rounded-full px-4" onClick={() => setAsking(true)}>{t('portal.leave', 'Cancel enrollment')}</Button>
+      <AlertDialog open={asking} onOpenChange={setAsking}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>{t('portal.leaveTitle', 'Cancel this enrollment?')}</AlertDialogTitle>
+            <AlertDialogDescription>{t('portal.leaveBody', 'Your seat goes back to the session, and someone else may take it.')}</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter className="max-sm:[&_button]:h-11">
+            <AlertDialogCancel>{t('portal.keep', 'Keep it')}</AlertDialogCancel>
+            <AlertDialogAction variant="destructive" onClick={() => {
+              setAsking(false)
+              void leave()
+            }}>{t('portal.leave', 'Cancel enrollment')}</AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  )
+}
+
+/** Every seat the viewer reads as a table, with each seat's student where the viewer reads people. */
+function SeatTable({ seats, people }: { seats: readonly Seat[]; people: boolean }) {
+  const { locale, t } = useLocale()
+  const screen = useScreen()
+  const place = usePlace()
+  return (
+    <div className="bg-card overflow-x-auto rounded-2xl">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>{t('courses.singular', 'Course')}</TableHead>
+            <TableHead>{t('sessions.singular', 'Session')}</TableHead>
+            <TableHead>{t('portal.place', 'Venue and format')}</TableHead>
+            {people ? <TableHead>{t('enrollments.student', 'Student')}</TableHead> : null}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {seats.map((one) => (
+            <TableRow key={String(one.seat.id)}>
+              <TableCell>
+                <a href={`${screen.path}/enrollments/${encodeURIComponent(String(one.seat.id))}`} className="flex items-center gap-2.5 font-medium underline-offset-4 hover:underline">
+                  <Cover course={one.course} cover={one.cover} className="size-9 shrink-0 rounded-lg" />
+                  {String(one.course?.title ?? t('admin.notAvailable', 'Not available'))}
+                </a>
+              </TableCell>
+              <TableCell className="whitespace-nowrap">{whenOf({ value: one.startsAt, locale })}</TableCell>
+              <TableCell>{place(one.session)}</TableCell>
+              {people ? <TableCell>{typeof one.student?.name === 'string' ? one.student.name : t('admin.notAvailable', 'Not available')}</TableCell> : null}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  )
+}

package/template/templates/features/courses/portal/ui/parts.tsx

@@ -0,0 +1,95 @@
+// What the portal's pages draw alike: a course's cover, its tags, its card, and a session's place.
+import type { ReactNode } from 'react'
+import type { Row } from 'mithaq/admin'
+import { useLocale, useScreen } from 'mithaq/admin/react'
+import { Skeleton } from '@/components/ui/skeleton'
+import { display } from './shell.tsx'
+import { feeOf, inLocale, whenOf } from './rules.ts'
+
+/** A text field's option in the viewer's words, as a choice reads it on every screen, and the stored value where none is declared. */
+export const useOption = () => {
+  const { locale } = useLocale()
+  const screen = useScreen()
+  return (kayan: string, field: string, value: unknown) => {
+    if (typeof value !== 'string' || !value) return undefined
+    const option = screen.kayan[kayan]?.fields.find((one) => one.name === field)?.options?.find((one) => one.value === value)
+    return inLocale(option?.label, locale) ?? value
+  }
+}
+
+/** Where and how a session meets, each part the viewer reads: "Campus · Workshop". */
+export const usePlace = () => {
+  const option = useOption()
+  return (session?: Row) => [option('sessions', 'venue', session?.venue), option('sessions', 'format', session?.format)].filter(Boolean).join(' · ')
+}
+
+/** Each cover that has no image is one of the portal's own colors, the same one for a course every time. */
+const grounds = ['bg-primary', 'bg-[var(--portal-amber)]', 'bg-[#9CC9C5] dark:bg-[#2F5654]']
+
+/**
+ * A course's cover: its image through the file route, which the image's own access guards, or a ground of the
+ * portal's colors. It says nothing a screen reader needs, since the course's title is beside it.
+ */
+export function Cover({ course, cover, className }: { course?: Row; cover?: Row; className: string }) {
+  const url = typeof cover?.url === 'string' ? cover.url : undefined
+  if (url) return <img src={url} alt="" loading="lazy" decoding="async" className={`object-cover ${className}`} />
+  const at = [...String(course?.id ?? '')].reduce((sum, letter) => sum + letter.charCodeAt(0), 0) % grounds.length
+  return <div aria-hidden className={`${grounds[at]} ${className}`} />
+}
+
+/** A course's tags, each by its name in the viewer's locale; a tag it may not read is left out. */
+export function Tags({ course, tags }: { course: Row; tags: ReadonlyMap<string, Row> }) {
+  const { locale } = useLocale()
+  const names = (Array.isArray(course.tags) ? course.tags : []).flatMap((id) => {
+    const name = inLocale(tags.get(String(id))?.name, locale)
+    return name ? [name] : []
+  })
+  if (!names.length) return null
+  return (
+    <ul className="flex flex-wrap gap-1.5">
+      {names.map((name) => <li key={name} className="bg-accent text-accent-foreground rounded-full px-2.5 py-0.5 text-xs">{name}</li>)}
+    </ul>
+  )
+}
+
+/** One course on offer: its cover, tags, title, summary, next session and fee, all one link to its page. */
+export function CourseCard({ course, cover, next, tags, href }: { course: Row; cover?: Row; next?: Row; tags: ReadonlyMap<string, Row>; href: string }) {
+  const { locale, t } = useLocale()
+  const fee = feeOf({ fee: course.fee, currency: course.currency, locale, t })
+  const when = whenOf({ value: next?.startsAt, locale })
+  return (
+    <a href={href} className="bg-card text-card-foreground focus-visible:ring-ring flex flex-col overflow-hidden rounded-2xl transition-shadow hover:shadow-md focus-visible:ring-2 focus-visible:outline-none">
+      <Cover course={course} cover={cover} className="h-36 w-full" />
+      <div className="flex flex-1 flex-col gap-2 p-4">
+        <Tags course={course} tags={tags} />
+        <h2 className={`${display} text-lg leading-snug`}>{String(course.title ?? '')}</h2>
+        {typeof course.summary === 'string' && course.summary ? <p className="text-muted-foreground line-clamp-2 text-sm leading-relaxed">{course.summary}</p> : null}
+        <div className="mt-auto flex items-center justify-between gap-3 pt-1 text-sm">
+          <span className="text-muted-foreground">{when ? `${t('portal.next', 'Next session')} · ${when}` : t('portal.noSession', 'No session scheduled yet')}</span>
+          {fee ? <span className="text-primary shrink-0 font-semibold"><bdi>{fee}</bdi></span> : null}
+        </div>
+      </div>
+    </a>
+  )
+}
+
+/** What stands where cards are still being read, the same shape so nothing jumps when they arrive. */
+export function CardsLoading({ count = 3 }: { count?: number }) {
+  const { t } = useLocale()
+  return (
+    <div role="status" aria-label={t('admin.loading', 'Loading…')} className="grid grid-cols-[repeat(auto-fill,minmax(16rem,1fr))] gap-5">
+      {Array.from({ length: count }, (_, at) => <Skeleton key={at} className="h-72 rounded-2xl" />)}
+    </div>
+  )
+}
+
+/** A failed read, said once, with the way to try again. */
+export function ReadFailed({ retry }: { retry: () => void }): ReactNode {
+  const { t } = useLocale()
+  return (
+    <p role="alert" className="text-muted-foreground text-sm">
+      {t('portal.failed', 'This could not be read just now.')}{' '}
+      <button type="button" onClick={retry} className="text-primary font-medium underline-offset-4 hover:underline">{t('portal.retry', 'Try again')}</button>
+    </p>
+  )
+}

package/template/templates/features/courses/portal/ui/reads.ts

@@ -0,0 +1,76 @@
+// What the portal's pages read, each read the viewer's own through the screen's client, so a row the viewer may
+// not read is left out of what comes back and a page draws what it can.
+import type { FetchClient, Row } from 'mithaq/admin'
+import { onOffer } from '../../domain/on-offer.ts'
+import { nextByCourse } from './rules.ts'
+
+type Reads = { client: FetchClient; maxLimit: number }
+type Found = { docs: Row[]; totalDocs: number }
+
+const find = ({ client, kayan, input }: { client: FetchClient; kayan: string; input: Record<string, unknown> }) =>
+  client({ kayan, operation: 'find', input }) as Promise<Found>
+
+/** A read the viewer may not make is an empty one; anything else failed and throws, for the query to try again. */
+const unread = (thrown: unknown): never[] => {
+  const key = (thrown as { data?: { key?: unknown } } | null)?.data?.key
+  if (typeof key === 'string' && key.startsWith('error.forbidden')) return []
+  throw thrown
+}
+
+const idsOf = (rows: readonly Row[], field: string) =>
+  [...new Set(rows.flatMap((one) => { const value = one[field]; return Array.isArray(value) ? value : [value] }).filter((id): id is string => typeof id === 'string'))].sort()
+
+/** Some rows of one kayan by id, as the viewer reads them, a page of the build's cap at a time. */
+export const byIds = async ({ client, kayan, ids, maxLimit }: Reads & { kayan: string; ids: readonly string[] }): Promise<Map<string, Row>> => {
+  const rows: Row[] = []
+  for (let at = 0; at < ids.length; at += maxLimit) {
+    const piece = ids.slice(at, at + maxLimit)
+    rows.push(...(await find({ client, kayan, input: { where: { id: { in: piece } }, limit: piece.length } }).then((found) => found.docs, unread)))
+  }
+  return new Map(rows.map((one) => [String(one.id), one]))
+}
+
+export type Catalogue = { courses: Row[]; next: Map<string, Row>; covers: Map<string, Row>; tags: Map<string, Row> }
+
+/**
+ * The courses on offer, published and not archived, by title, each with its next session, its cover and its
+ * tags. A plain read answers the published courses alone, whoever reads.
+ */
+export const catalogueOf = async ({ client, maxLimit, now }: Reads & { now: number }): Promise<Catalogue> => {
+  // ponytail: one page of the build's cap, searched and filtered in the browser; a server search and pages once a
+  // school offers more courses than that.
+  const courses = (await find({ client, kayan: 'courses', input: { where: onOffer, sort: 'title', limit: maxLimit } })).docs
+  const ids = idsOf(courses, 'id')
+  const [sessions, covers, tags] = await Promise.all([
+    ids.length
+      ? find({ client, kayan: 'sessions', input: { where: { and: [{ course: { in: ids } }, { startsAt: { greater_than: new Date(now).toISOString() } }] }, sort: 'startsAt', limit: maxLimit } }).then((found) => found.docs, unread)
+      : [],
+    byIds({ client, maxLimit, kayan: 'media', ids: idsOf(courses, 'cover') }),
+    byIds({ client, maxLimit, kayan: 'tags', ids: idsOf(courses, 'tags') }),
+  ])
+  return { courses, next: nextByCourse(sessions, now), covers, tags }
+}
+
+/** One seat as the portal draws it: its session, the session's course and that course's cover, and its student. */
+export type Seat = { seat: Row; startsAt?: unknown; session?: Row; course?: Row; cover?: Row; student?: Row }
+
+/**
+ * The seats the viewer reads, the newest first, each with what it draws. `where` narrows them, as the home does to
+ * the viewer's own. People are read only where `people` is set, and each is one the viewer may read: a name the
+ * server keeps from it is left out.
+ */
+export const readSeats = async ({ client, maxLimit, where, people = false }: Reads & { where?: Row; people?: boolean }): Promise<Seat[]> => {
+  // ponytail: one page of the build's cap, the newest; pages once a viewer holds more seats than that.
+  const seats = (await find({ client, kayan: 'enrollments', input: { sort: '-createdAt', limit: maxLimit, ...(where && { where }) } })).docs
+  const sessions = await byIds({ client, maxLimit, kayan: 'sessions', ids: idsOf(seats, 'session') })
+  const courses = await byIds({ client, maxLimit, kayan: 'courses', ids: idsOf([...sessions.values()], 'course') })
+  const [covers, students] = await Promise.all([
+    byIds({ client, maxLimit, kayan: 'media', ids: idsOf([...courses.values()], 'cover') }),
+    people ? byIds({ client, maxLimit, kayan: 'user', ids: idsOf(seats, 'student') }) : new Map<string, Row>(),
+  ])
+  return seats.map((seat) => {
+    const session = sessions.get(String(seat.session))
+    const course = session && courses.get(String(session.course))
+    return { seat, startsAt: session?.startsAt, session, course, cover: course && covers.get(String(course.cover)), student: students.get(String(seat.student)) }
+  })
+}