create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/features/courses/courses/ui/fee-cell.tsx

@@ -0,0 +1,19 @@
+// A row with no currency, one the reader may not read, or one Intl does not know keeps the plain
+// number. The amount is a left-to-right isolate so Arabic neither reads "US$" as "$US" nor strands
+// the dot of "ر.س." on the wrong side.
+import type { CellProps } from 'mithaq/admin'
+import { useLocale } from 'mithaq/admin/react'
+import { noValue } from 'mithaq-admin/format.tsx'
+
+const amount = (text: string) => <bdi dir="ltr">{text}</bdi>
+
+export function FeeCell({ value, row }: CellProps) {
+  const { locale } = useLocale()
+  if (typeof value !== 'number') return noValue
+  try {
+    if (typeof row.currency === 'string' && row.currency) return amount(new Intl.NumberFormat(locale, { style: 'currency', currency: row.currency }).format(value))
+  } catch {
+    // A code Intl refuses throws a RangeError; the number alone is still true.
+  }
+  return amount(value.toLocaleString(locale))
+}

package/template/templates/features/courses/courses/ui/no-courses.tsx

@@ -0,0 +1,13 @@
+// What the courses list draws when it holds no row, and what the board page
+// draws by path: the same file under a registered name and an inline path.
+import type { EmptyProps } from 'mithaq/admin'
+import { useKayan, useLocale } from 'mithaq/admin/react'
+
+export function NoCourses({ page }: EmptyProps) {
+  const { t } = useLocale()
+  return (
+    <p data-empty={`${useKayan().name}${page.path}`} className="text-muted-foreground text-sm">
+      {t('courses.none', 'No courses yet.')}
+    </p>
+  )
+}

package/template/templates/features/courses/courses/ui/status-cell.tsx

@@ -0,0 +1,33 @@
+// The list reads each row's latest draft, so a published course whose newest version is a draft
+// and a never-published course both arrive as `draft`. The plain read finds only courses with a
+// published copy, which tells the two apart. An archived course says so over any of the three.
+import { use } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import type { CellProps, Row } from 'mithaq/admin'
+import { ListContext, useClient, useLocale, useScreen } from 'mithaq/admin/react'
+import { Badge } from '@/components/ui/badge'
+import { noValue } from 'mithaq-admin/format.tsx'
+import { coursesOf } from '../../enrollments/ui/session-cell.tsx'
+
+const pills = {
+  draft: 'bg-muted text-muted-foreground',
+  published: 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-400',
+  changed: 'bg-amber-500/15 text-amber-700 dark:text-amber-400',
+  archived: 'bg-destructive/10 text-destructive',
+}
+const words = { draft: 'Draft', published: 'Published', changed: 'Changed', archived: 'Archived' }
+
+export function StatusCell({ value, row }: CellProps) {
+  const client = useClient()
+  const { t } = useLocale()
+  const { maxLimit } = useScreen()
+  // Sorted, so the same rows in another order are the same query.
+  const ids = [...new Set((use(ListContext)?.page.docs ?? [row]).flatMap((one: Row) => (one._status === 'draft' ? [String(one.id)] : [])))].sort()
+  const { data: published, isError } = useQuery({ queryKey: ['status-cell', ids], queryFn: () => coursesOf({ client, ids, maxLimit }), enabled: ids.length > 0, staleTime: 30_000 })
+  if (value !== 'draft' && value !== 'published') return noValue
+  if (row.archived === true) return <Badge data-status="archived" className={pills.archived}>{t('version.archived', words.archived)}</Badge>
+  // Loading until the read answers, and a draft where it failed, which is what the row itself holds.
+  if (value === 'draft' && !published && !isError) return t('admin.loading', 'Loading…')
+  const status = value === 'draft' && published?.has(String(row.id)) ? 'changed' : value
+  return <Badge data-status={status} className={pills[status]}>{t(`version.${status}`, words[status])}</Badge>
+}

package/template/templates/features/courses/courses/ui/unpublish-button.tsx

@@ -0,0 +1,15 @@
+// The danger zone's Unpublish: one click, behind the page's confirm, sending the
+// draft status `unpublish` takes, as Payload's Unpublish does. The course stays
+// as it is, read by draft readers alone, until it is published again.
+import type { ButtonProps } from 'mithaq/admin'
+import { useLocale } from 'mithaq/admin/react'
+import { Button } from '@/components/ui/button'
+
+export function UnpublishButton({ busy, operation, run }: ButtonProps) {
+  const { t } = useLocale()
+  return (
+    <Button type="button" variant="outline" data-button={operation} disabled={busy} onClick={() => void run({ _status: 'draft' })}>
+      {t('courses.operations.unpublish', 'Unpublish')}
+    </Button>
+  )
+}

package/template/templates/features/courses/domain/archive.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod'
+import type { Ctx } from 'mithaq'
+
+/** The box an archive's or an unarchive's dialog asks for on every screen that draws its button. */
+export const reason = {
+  kind: 'text',
+  label: { en: 'Reason', ar: 'السبب' },
+  rules: { required: true, maxLength: 200 },
+} as const
+
+/**
+ * What `archive` and `unarchive` parse: the row and why. The error messages are
+ * the kayan's own copy keys, which the form resolves; without them it draws
+ * what zod wrote, in English.
+ */
+export const reasonInput = (key: `${string}.operations.${'archive' | 'unarchive'}`) => z.object({
+  id: z.guid(),
+  reason: z
+    .string({ error: `${key}.reason.required` })
+    .max(200, { error: `${key}.reason.maxLength` }),
+})
+
+/**
+ * The one step each adds: it turns the operation's `reason` into the two
+ * columns the kayan has, so `reason` never has to be a field. `ctx.data` is
+ * spread to keep what the runner filled before it, such as `updatedAt`, and
+ * `reason` reaches no column: the store step writes the kayan's own fields alone.
+ * An empty reason, which a bulk archive sends, keeps none.
+ */
+export const marks = (archived: boolean) => (ctx: Ctx<{ reason: string }>): Ctx => ({ ...ctx, data: { ...ctx.data, archived, archiveReason: ctx.data.reason || null } })
+
+/** Over a row not archived yet, where an archive button is drawn. Both arms, since a row from before the column holds `null`. */
+export const unarchived = { or: [{ 'record.archived': { exists: false } }, { 'record.archived': { equals: false } }] } as const
+
+/** Over an archived row, where an unarchive button and the Archived badge are drawn. */
+export const archivedRow = { 'record.archived': { equals: true } } as const
+
+/** A list's tabs over the same column: what is running, what was archived, and everything. */
+export const notArchived = { or: [{ archived: { exists: false } }, { archived: { equals: false } }] } as const

package/template/templates/features/courses/domain/on-offer.ts

@@ -0,0 +1,6 @@
+// The courses the portal offers: every course not archived, of those a plain
+// read answers, which are the published ones. The portal's catalogue, its home
+// and its course page read these alone. Plain data in a file of its own, so a
+// page reads it without the kayan's declaration. A course with no `archived`
+// value is not archived either.
+export const onOffer = { or: [{ archived: { exists: false } }, { archived: { equals: false } }] }

package/template/templates/features/courses/enrollments/enrollments.ts

@@ -0,0 +1,309 @@
+import { conflict, defaultOperations, folderOf, invalid, type Ctx, type FilterOptions, type WriteTools } from 'mithaq'
+import { defineKayan, organization, serverTargets } from '@asas/mithaq'
+import { currentOrganization, readsPast, user as actor } from '@asas/mithaq/roles/tenant-access.ts'
+import { activity, appPage, danger, backofficeList, backofficeRecord } from '@asas/mithaq/mithaq/pages.ts'
+import { sessions } from '../sessions/sessions.ts'
+import { holdSeats, seatsTaken, sessionHeld } from '../sessions/seats.ts'
+// add-on: settings
+import { sql } from 'mithaq/drizzle'
+import type { NodePgDatabase } from 'mithaq/drizzle/node-postgres'
+// end add-on: settings
+
+const ui = folderOf(new URL('./ui/', import.meta.url))
+const portalUi = folderOf(new URL('../portal/ui/', import.meta.url))
+/** A portal page in its shell, which draws the portal's own nav, over its single column. */
+const portalPage = <const Main extends readonly unknown[]>(main: Main) => ({ shell: 'top', header: [{ title: {} }], main: [{ layout: 'page', main }] }) as const
+const sessionCell = ui('session-cell.tsx#SessionCell')
+const enrollment = [{ section: 'enrollment', label: { en: 'Enrollment', ar: 'التسجيل' }, fields: ['session', 'student'] }] as const
+
+/**
+ * The seats an actor reads, edits and deletes, inside its active organization:
+ * every seat of its organization for an actor holding
+ * `enrollments.others` and for backoffice staff, its own seats alone for anyone
+ * else. That is the student, whose enrollment keys would otherwise reach every
+ * other student's seat, and a custom role a tenant writes without the key.
+ * Another's seat answers 404, as a missing row does.
+ *
+ * The id is read off the actor as an own key, and an actor carrying none reaches
+ * no seat. Every read answers from it, a session's join of its enrollments
+ * included.
+ */
+const ownId = (user: unknown) => {
+  const actor = user && typeof user === 'object' ? (user as Record<string, unknown>) : undefined
+  const id = actor && Object.hasOwn(actor, 'id') ? actor.id : undefined
+  return typeof id === 'string' && id ? id : undefined
+}
+const ownSeats = ({ user }: { user: unknown }) => {
+  if (readsPast(user, 'enrollments.others')) return true
+  const id = ownId(user)
+  return id ? { student: { equals: id } } : false
+}
+
+/**
+ * Whether a write names another person as a seat's student for an actor that
+ * writes its own seats alone. Refused on a create and on an update, so a seat
+ * is never made for, or handed to, someone the actor may not write for.
+ */
+const namesAnother = ({ user, data }: { user: unknown; data?: unknown }) =>
+  !readsPast(user, 'enrollments.others') && !!data && typeof data === 'object' && Object.hasOwn(data, 'student')
+  && (data as { student?: unknown }).student !== ownId(user)
+
+/**
+ * Whom a seat's student picker offers: the people holding the student role in
+ * the active organization, a teacher who also studies among them. It narrows
+ * what the actor's own read of people answers and never widens it, so an
+ * instructor is offered the students it already reads and not itself.
+ */
+const students: FilterOptions = async ({ user, tx }) => {
+  const active = currentOrganization(user)
+  if (!active) return false
+  const held = await serverTargets.drizzle.find({ tx, kayan: 'memberRoles', args: { limit: 0, page: 1, sort: { field: 'id', direction: 'asc' }, where: { organization: { equals: active }, role: { equals: 'student' } } } })
+  const ids = held.docs.map((row) => row.user).filter((id): id is string => typeof id === 'string')
+  return ids.length ? { id: { in: ids } } : false
+}
+
+/** Not archived, the column read by its name, or across a session's course. */
+const open = (path: string) => ({ or: [{ [path]: { exists: false } }, { [path]: { equals: false } }] })
+
+/** What a seat's session picker offers, and a save is held to: a session open for seats, of a course open too. */
+const openSessions: FilterOptions = () => ({ and: [open('archived'), open('course.archived')] })
+
+/** Whether the actor writes its own seats alone: a student, held to what each course lets its students do. */
+const ownSeatsOnly = (user: unknown) => !readsPast(user, 'enrollments.others')
+
+/** Whether a session is still to start, which a student's enrollment and its cancel both ask. */
+const yetToStart = (startsAt: unknown) => new Date(startsAt as string | Date).getTime() > Date.now()
+
+/**
+ * Whether a session takes this seat. A session the actor may not read is left
+ * to the reference check, which refuses it in the words a missing one gets.
+ * The rest is judged on the session's own columns, whatever the actor is shown:
+ * an archived session, or one of an archived course, takes none; a student
+ * takes a seat only where its course lets students enroll themselves, and only
+ * before the session starts; and a session with a capacity takes no seat past
+ * it, whoever writes, counted under a lock on the session. A seat kept in the
+ * session it already holds takes no new one.
+ */
+const takesSeat = async (ctx: Ctx<{ session?: unknown }>, tools: WriteTools): Promise<Ctx> => {
+  const id = ctx.data.session
+  // An edit of a seat the actor may not reach loaded no row; the store answers it the 404 a missing one gets.
+  if (typeof id !== 'string' || (tools.operation !== 'create' && !ctx.dataBefore)) return ctx
+  if (!(await tools.of(sessions).findByID({ id }).catch(() => null))) return ctx
+  const session = await sessionHeld({ tx: ctx.tx, session: id })
+  if (!session) return ctx
+  // The stored id from here on: a uuid matches in any case, and the lock, the count and the comparison below must not
+  // tell `A0EE…` from `a0ee…`.
+  const held = session.id
+  if (session.archived || session.courseArchived) {
+    throw invalid({
+      message: 'This session is archived, or its course is, so it takes no new seat.',
+      key: 'error.invalid.archived_session',
+      params: { kayan: 'enrollments', field: 'session' },
+    })
+  }
+  if (held === ctx.dataBefore?.session) return ctx
+  if (ownSeatsOnly(ctx.user)) {
+    if (session.selfEnroll !== true) {
+      throw invalid({
+        message: 'Students of this course do not enroll themselves: the school enrolls them.',
+        key: 'error.invalid.enrollment_closed',
+        params: { kayan: 'enrollments', field: 'session' },
+      })
+    }
+    if (!yetToStart(session.startsAt)) {
+      throw invalid({ message: 'This session has started, so it takes no new seat.', key: 'error.invalid.session_started', params: { kayan: 'enrollments', field: 'session' } })
+    }
+  }
+  if (session.capacity !== null) {
+    await holdSeats({ tx: ctx.tx, session: held })
+    if ((await seatsTaken({ session: held, tx: ctx.tx })) >= session.capacity) {
+      throw conflict({ message: 'Every seat of this session is taken.', key: 'error.conflict.session_full', params: { kayan: 'enrollments', field: 'session' } })
+    }
+  }
+  return ctx
+}
+
+/**
+ * A student leaves a session only before it starts: the seat it held stays the
+ * record that it was there. Whoever reads every seat withdraws one at any time.
+ * A seat the actor may not reach loaded no row, and answers the 404 a missing
+ * one does. The start is the session's column, so a seat whose course has since
+ * left the actor's sight is not said to have started.
+ */
+const leavesBeforeStart = async (ctx: Ctx): Promise<Ctx> => {
+  if (!ownSeatsOnly(ctx.user) || !ctx.dataBefore) return ctx
+  const id = ctx.dataBefore.session
+  const session = typeof id === 'string' ? await sessionHeld({ tx: ctx.tx, session: id }) : undefined
+  if (!session || !yetToStart(session.startsAt)) {
+    throw invalid({ message: 'This session has started, so its seat stays.', key: 'error.invalid.session_started', params: { kayan: 'enrollments' } })
+  }
+  return ctx
+}
+
+// add-on: settings
+/**
+ * While the portal is closed for maintenance a student takes and gives back no
+ * seat, whatever calls the server; staff keep working. The organization's
+ * settings are read in the write's own transaction, since a student reads them
+ * as itself and a role might not.
+ */
+// The table and column are written out, as `sessionHeld`'s are; R7g fails on a rename.
+const portalOpen = async (ctx: Ctx): Promise<Ctx> => {
+  if (!ownSeatsOnly(ctx.user) || !ctx.tenant) return ctx
+  const [held] = (await (ctx.tx as NodePgDatabase).execute<{ maintenance: boolean | null }>(sql`select maintenance from settings where organization_id = ${ctx.tenant}`)).rows
+  if (held?.maintenance === true) {
+    throw invalid({ message: 'The portal is closed for maintenance, so no seat changes from it.', key: 'error.invalid.portal_closed', params: { kayan: 'enrollments' } })
+  }
+  return ctx
+}
+// end add-on: settings
+
+export const enrollments = defineKayan({
+  name: 'enrollments',
+  access: {
+    read: ownSeats,
+    create: (args: { user: unknown; data?: unknown }) => !namesAnother(args),
+    update: (args: { user: unknown; data?: unknown }) => (namesAnother(args) ? false : ownSeats(args)),
+    delete: ownSeats,
+  },
+  // What a form says where a second seat of one student in one session is
+  // refused, over the shared words for a unique value taken.
+  messages: {
+    conflict: { unique: { en: 'This student already holds a seat in this session.', ar: 'لهذا الطالب مقعد في هذه الحصة بالفعل.' } },
+  },
+  // A student holds one seat in a session, which is one organization's, so the
+  // organization needs no column in the key. The mark is in it with its nulls
+  // not distinct, so a withdrawn seat makes room for a new one while two
+  // standing seats collide.
+  indexes: [{ fields: ['session', 'student', 'deletedAt'], unique: true, nullsNotDistinct: true }],
+  fields: ({ defaults }) => ({
+    ...defaults,
+    organization,
+    // Read as the session's course and its start on every screen, where a
+    // session alone is titled by its start.
+    //
+    // Both are required, so no write makes a seat for nobody or in nothing, and
+    // a session or a person that holds one is not deleted under it: a required
+    // relationship restricts.
+    session: {
+      kind: 'relationship', label: { en: 'Session', ar: 'الحصة' }, relationTo: () => sessions,
+      filterOptions: openSessions,
+      rules: { required: true },
+      targets: { dashboard: { cell: sessionCell }, portal: { cell: sessionCell }, backoffice: { cell: sessionCell } },
+    },
+    // A create that names no student enrolls the person making it: the runner's
+    // defaults step fills it from the actor, and a field with a default is one a
+    // create may leave out, at the HTTP boundary too. A role without the column's
+    // key is refused the filled value. A student holds it, so its own enrollment
+    // names itself, and `namesAnother` refuses it any other person.
+    student: {
+      kind: 'relationship', label: { en: 'Student', ar: 'الطالب' }, relationTo: 'user',
+      filterOptions: students,
+      rules: { required: true, defaultValue: actor.id },
+    },
+    /**
+     * The field the language names as its soft-delete mark, so a student who
+     * leaves a session is a row this kayan keeps rather than one it removes: an
+     * enrollment is the record that the student was there. It is the one kayan
+     * of this template that takes the mark. Nothing points at an enrollment, so
+     * no child outlives it, and nothing refers to it through a `restrict`
+     * foreign key that a delete would have to release. Nobody supplies the
+     * mark: the runner writes it at the delete.
+     *
+     * `session` and `student` are required, so each restricts, and a session or
+     * a person a marked enrollment still names is not deleted under it.
+     */
+    deletedAt: {
+      kind: 'datetime',
+      label: { en: 'Deleted at', ar: 'تاريخ الحذف' },
+      rules: { providedBy: { create: 'never', update: 'never' } },
+    },
+  }),
+  targets: {
+    // Every organization's rows on the backoffice, read-only, and each row's
+    // record, which only reads. A record is titled by its student, a person the
+    // backoffice reads, where a session is titled only by its start.
+    backoffice: {
+      useAsTitle: 'student',
+      pages: {
+        ...backofficeList('/enrollments', { columns: ['session', 'student', 'organization', 'createdAt'], filters: ['organization', 'session', 'student'], sort: '-createdAt' }),
+        ...backofficeRecord({
+          path: '/enrollments/:id',
+          main: [{ section: 'enrollment', label: { en: 'Enrollment', ar: 'التسجيل' }, fields: ['session', 'student', 'deletedAt'] }],
+        }),
+      },
+    },
+    service: {
+      operations: {
+        ...defaultOperations,
+        create: { ...defaultOperations.create, steps: ({ steps }) => [
+          // add-on: settings
+          portalOpen,
+          // end add-on: settings
+          takesSeat,
+          steps.insert,
+        ] },
+        update: { ...defaultOperations.update, steps: ({ steps }) => [
+          // add-on: settings
+          portalOpen,
+          // end add-on: settings
+          takesSeat,
+          steps.update,
+        ] },
+        delete: { ...defaultOperations.delete, steps: ({ steps }) => [
+          // add-on: settings
+          portalOpen,
+          // end add-on: settings
+          leavesBeforeStart,
+          steps.remove,
+        ] },
+      },
+    },
+    // Titled by the student on the dashboard, as on the backoffice, so a tab and a
+    // heading tell one seat from another; on the portal, where the student is most
+    // often the viewer, by the session.
+    dashboard: {
+      useAsTitle: 'student',
+      description: {
+        en: 'Which student holds a seat in which session.',
+        ar: 'أي طالب يشغل مقعدا في أي حصة.',
+      },
+      pages: {
+        // The same table every kayan's list is. Searched by the student's name,
+        // the one column of a person a tenant reads, and filtered by session,
+        // student and when the student enrolled, as the course list is.
+        list: { path: '/enrollments', page: appPage([{ layout: 'table', main: [{ list: {
+          columns: ['session', 'student', 'createdAt'],
+          filters: ['session', 'student', 'createdAt'],
+          search: ['student.name'],
+        } }] }]) },
+        create: { path: '/enrollments/new', page: appPage([{ layout: 'record', main: [{ form: enrollment }] }]) },
+        // The editor layout, and the one timestamp worth reading here, named and
+        // read-only: when the student enrolled. Not the organization, which on the
+        // dashboard is always the active one.
+        edit: {
+          path: '/enrollments/:id',
+          page: appPage([{
+            layout: 'record',
+            main: [{ form: enrollment }],
+            side: [{ section: 'record', label: { en: 'Record', ar: 'السجل' }, fields: [{ field: 'createdAt', readOnly: true }] }, activity],
+            danger: danger(),
+          }]),
+        },
+      },
+    },
+    portal: {
+      useAsTitle: 'session',
+      pages: {
+        // The viewer's seats, upcoming first, drawn whole by the courses feature's portal.
+        list: { path: '/enrollments', component: portalUi('enrollments.tsx#Enrollments') },
+        // The list's New enrollment, which only staff are offered, with the
+        // student as the dashboard draws it, so an instructor picks whom it
+        // enrolls. A student who opens it by its address and names another is
+        // refused by `namesAnother`; one who names nobody enrolls itself.
+        create: { path: '/enrollments/new', page: portalPage([{ form: ['session', 'student'] }]) },
+        edit: { path: '/enrollments/:id', page: portalPage([{ form: ['session'] }]) },
+      },
+    },
+  },
+})

package/template/templates/features/courses/enrollments/ui/session-cell.tsx

@@ -0,0 +1,75 @@
+// What an enrollment's session column draws: the session's course by its title, then when it starts, which tells two sessions of one course apart,
+// then where and how it meets.
+// A session is titled by its start and a title is one field, so the course is a second read.
+//
+// The list's own `useRelationshipTitles` keeps only each session's title, the start as text, and not the course it points at, so this cell reads them again:
+// one read of every session the page's rows point at and one of their courses, shared by every cell of the page through the query client rather than two per cell,
+// and read again once it is as old as the list's own pages. A read that failed is not kept, so the next one tries again.
+// Each read is the viewer's own, so a session or a course the viewer may not read is left out, and its cell keeps what it can say.
+import { use } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import type { CellProps, FetchClient, Row } from 'mithaq/admin'
+import { ListContext, useClient, useLocale, useScreen } from 'mithaq/admin/react'
+import type { FoundPage } from 'mithaq-admin/control-props.ts'
+import { formatDate, noValue } from 'mithaq-admin/format.tsx'
+import { refusalKeyOf } from 'mithaq-admin/refusal.ts'
+import { findByIds, nameOfRow, titleFieldOf } from 'mithaq-admin/relationship-control.tsx'
+
+/** A refusal is the viewer's access answering, so it reads as no rows; anything else is a failure, and throws for the query to try again. */
+const unread = (thrown: unknown): never[] => {
+  if (refusalKeyOf(thrown)) return []
+  throw thrown
+}
+
+const of = (client: FetchClient, kayan: string) => ({ find: (input: Record<string, unknown>) => client({ kayan, operation: 'find', input }) as Promise<FoundPage> })
+
+/** Some courses by id, as the viewer reads them, which the session picker's label reads too. */
+export const coursesOf = async ({ client, ids, maxLimit }: { client: FetchClient; ids: readonly string[]; maxLimit: number }): Promise<ReadonlyMap<string, Row>> => {
+  const courses = ids.length ? await findByIds({ reads: of(client, 'courses'), ids, maxLimit }).catch(unread) : []
+  return new Map(courses.map((one) => [String(one.id), one]))
+}
+
+const sessionsOf = async ({ client, ids, maxLimit }: { client: FetchClient; ids: readonly string[]; maxLimit: number }): Promise<ReadonlyMap<string, Row>> => {
+  const sessions = await findByIds({ reads: of(client, 'sessions'), ids, maxLimit }).catch(unread)
+  const courseIds = [...new Set(sessions.flatMap((one) => (typeof one.course === 'string' ? [one.course] : [])))]
+  const course = await coursesOf({ client, ids: courseIds, maxLimit })
+  return new Map(sessions.map((one) => [String(one.id), { ...one, course: course.get(String(one.course)) }]))
+}
+
+export function SessionCell({ field, value, row }: CellProps) {
+  const client = useClient()
+  const { locale, t } = useLocale()
+  const { kayan: { courses, sessions: sessionKayan }, maxLimit } = useScreen()
+  // A list's page, or the one row a record page draws.
+  // Sorted, so the same rows in another order are the same query.
+  const ids = [...new Set((use(ListContext)?.page.docs ?? [row]).flatMap((one: Row) => (typeof one[field.name] === 'string' ? [one[field.name] as string] : [])))].sort()
+  const { data: sessions, isError } = useQuery({ queryKey: ['session-cell', ids], queryFn: () => sessionsOf({ client, ids, maxLimit }), staleTime: 30_000 })
+  if (typeof value !== 'string') return noValue
+  const session = sessions?.get(value)
+  const when = formatDate({ value: session?.startsAt, locale })
+  const course = session?.course ? nameOfRow({ row: session.course as Row, title: titleFieldOf(courses), locale }) : undefined
+  // Where and how it meets, each by its option's label in the viewer's locale, where the viewer reads it.
+  const labelOf = (name: string) => {
+    const option = sessionKayan?.fields.find((one) => one.name === name)?.options?.find((one) => one.value === session?.[name])
+    return option?.label[locale]
+  }
+  const place = [labelOf('venue'), labelOf('format')].filter(Boolean).join(' · ')
+  // Never the id the column holds, as the relationship cell draws none:
+  // loading until the read answers, the server's render among it, a dash
+  // where it failed, and not available for a session it may not read or one
+  // of which it may read neither the course nor the start.
+  if (!when && !course) {
+    if (sessions) return t('admin.notAvailable', 'Not available')
+    return isError ? '—' : t('admin.loading', 'Loading…')
+  }
+  // Two lines, the course over its start, so a narrow column wraps each
+  // whole rather than one into the other.
+  return (
+    <span className="grid">
+      {course ? <span className="font-medium">{course}</span> : null}
+      {/* One unbroken run, so a narrow column breaks between the course and the date and never inside the date. */}
+      {when ? <span className="text-muted-foreground text-xs"><bdi className="whitespace-nowrap">{when}</bdi></span> : null}
+      {place ? <span className="text-muted-foreground text-xs">{place}</span> : null}
+    </span>
+  )
+}

package/template/templates/features/courses/enrollments/ui/session-labels.tsx

@@ -0,0 +1,36 @@
+// How a session reads wherever a picker lists or holds one: its course by the
+// course's title, then when it starts, since a session's own title, the start
+// alone, makes two sessions on one day read alike.
+//
+// A session holds its course as an id, and a read populates no relationship, so
+// the courses are a second read: one of every course the picker's rows point at,
+// shared through the query client. Each read is the viewer's, so a course the
+// viewer may not read leaves the session's title, its start, as it was.
+import type { ReactNode } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import type { ProviderProps, Row } from 'mithaq/admin'
+import { useClient, useLocale, useScreen } from 'mithaq/admin/react'
+import { formatDate } from 'mithaq-admin/format.tsx'
+import { nameOfRow, RowLabelContext, titleFieldOf, type UseRowLabel } from 'mithaq-admin/relationship-control.tsx'
+import { coursesOf } from './session-cell.tsx'
+
+/** The session's course and its start, or nothing for any other kayan and for a session whose course is not read yet. */
+export const useSessionLabel: UseRowLabel = (target, rows) => {
+  const client = useClient()
+  const { locale } = useLocale()
+  const { kayan, maxLimit } = useScreen()
+  const sessions = target === 'sessions'
+  // Sorted, so the same courses in another order are the same query.
+  const ids = sessions ? [...new Set(rows.flatMap((one) => (typeof one.course === 'string' ? [one.course] : [])))].sort() : []
+  const { data: courses } = useQuery({ queryKey: ['session-courses', ids], queryFn: () => coursesOf({ client, ids, maxLimit }), enabled: ids.length > 0, staleTime: 30_000 })
+  if (!sessions) return undefined
+  return (row: Row) => {
+    const course = courses?.get(String(row.course))
+    const when = formatDate({ value: row.startsAt, locale })
+    // The date's own spaces are no-break ones, so a box too narrow for the whole label breaks between the course
+    // and the date and never inside the date.
+    return course && when ? `${nameOfRow({ row: course, title: titleFieldOf(kayan.courses), locale })} · ${when.replaceAll(' ', '\u00a0')}` : undefined
+  }
+}
+
+export const SessionLabels = ({ children }: ProviderProps<ReactNode>) => <RowLabelContext value={useSessionLabel}>{children}</RowLabelContext>

package/template/templates/features/courses/index.ts

@@ -0,0 +1,8 @@
+import { courses } from './courses/courses.ts'
+import { enrollments } from './enrollments/enrollments.ts'
+import { sessions } from './sessions/sessions.ts'
+
+export const kayan = [courses, sessions, enrollments] as const
+
+// The images a course's reader reads as its cover, which the asas hands the media feature.
+export { coverReads } from './courses/cover-reads.ts'

package/template/templates/features/courses/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@asas/courses",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./domain/*": "./domain/*",
+    "./portal/*": "./portal/*"
+  },
+  "dependencies": {
+    "@asas/mithaq": "*",
+    "@fontsource-variable/bricolage-grotesque": "^5.3.0",
+    "mithaq": "*",
+    "mithaq-admin": "*",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "lucide-react": "^1.16.0",
+    "react": "^19.3.0",
+    "@tanstack/react-query": "^5.104.0"
+  }
+}