create-mithaq 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,87 @@
+// What the portal's pages decide, apart from what they draw, so a test reads it under plain `node`.
+import { holds, type AccessReport, type Row, type Translate } from 'mithaq/admin'
+
+/** Which part of the day a greeting names, by the hour on the viewer's own clock. */
+export const partOfDay = (hour: number) => (hour < 12 ? 'morning' : hour < 18 ? 'afternoon' : 'evening')
+
+const timeOf = (value: unknown) => (value instanceof Date || typeof value === 'string' ? new Date(value).getTime() : Number.NaN)
+
+/** The first session of each course still to start, by the course's id. An archived session takes no seat, so it is never next. */
+export const nextByCourse = (sessions: readonly Row[], now: number): Map<string, Row> => {
+  const next = new Map<string, Row>()
+  for (const one of sessions) {
+    const at = timeOf(one.startsAt)
+    if (one.archived === true || !(at > now) || typeof one.course !== 'string') continue
+    const held = next.get(one.course)
+    if (!held || at < timeOf(held.startsAt)) next.set(one.course, one)
+  }
+  return next
+}
+
+/**
+ * Seats split by when their session meets: those to come, soonest first, and those past, latest first. A seat
+ * whose session the viewer cannot read has no start and is in neither.
+ */
+export const byWhen = <Seat extends { startsAt?: unknown }>(seats: readonly Seat[], now: number) => {
+  const timed = seats.filter((one) => !Number.isNaN(timeOf(one.startsAt)))
+  const upcoming = timed.filter((one) => timeOf(one.startsAt) > now).sort((a, b) => timeOf(a.startsAt) - timeOf(b.startsAt))
+  const past = timed.filter((one) => timeOf(one.startsAt) <= now).sort((a, b) => timeOf(b.startsAt) - timeOf(a.startsAt))
+  return { upcoming, past }
+}
+
+/** A fee in its own currency, a fee of nought as free, and nothing for a course that names none. */
+export const feeOf = ({ fee, currency, locale, t }: { fee: unknown; currency: unknown; locale: string; t: Translate }): string | undefined => {
+  if (typeof fee !== 'number') return undefined
+  if (fee === 0) return t('portal.free', 'Free')
+  try {
+    if (typeof currency === 'string' && currency) return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(fee)
+  } catch {
+    // A code Intl refuses throws a RangeError; the number alone is still true.
+  }
+  return fee.toLocaleString(locale)
+}
+
+/** What a session says of its seats: nothing where it holds any number, Full, or how many are left. */
+export const seatsOf = ({ seatsLeft, locale, t }: { seatsLeft: unknown; locale: string; t: Translate }): string | undefined => {
+  if (typeof seatsLeft !== 'number') return undefined
+  if (seatsLeft <= 0) return t('portal.full', 'Full')
+  // The plural form the locale takes for the count, as the admin's `counted` reads it, which lives in a `.tsx` file.
+  const form = t(`portal.seatsLeft_${new Intl.PluralRules(locale).select(seatsLeft)}`) ?? t('portal.seatsLeft_other', '{count} seats left')!
+  return form.replace('{count}', () => seatsLeft.toLocaleString(locale))
+}
+
+const hour = 60 * 60 * 1000
+
+/** How soon a moment comes, in the viewer's words: in hours under a day, in days past one. */
+export const startsIn = ({ value, now, locale }: { value: unknown; now: number; locale: string }): string | undefined => {
+  const at = timeOf(value)
+  if (Number.isNaN(at)) return undefined
+  const words = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+  const hours = Math.round((at - now) / hour)
+  return Math.abs(hours) < 24 ? words.format(hours, 'hour') : words.format(Math.round(hours / 24), 'day')
+}
+
+/** A moment as a student reads it on a card: the day of the week, the date and the time, in the viewer's locale. */
+export const whenOf = ({ value, locale }: { value: unknown; locale: string }): string | undefined => {
+  const at = timeOf(value)
+  if (Number.isNaN(at)) return undefined
+  const date = new Date(at)
+  const day = new Intl.DateTimeFormat(locale, { weekday: 'long', month: 'short', day: 'numeric' }).format(date)
+  return `${day} · ${new Intl.DateTimeFormat(locale, { timeStyle: 'short' }).format(date)}`
+}
+
+/**
+ * Whether maintenance closes the portal to this viewer. It closes it to a student alone: whoever enters the
+ * dashboard runs the school, and whoever reads every seat teaches, so both keep working through it.
+ */
+export const closedTo = ({ maintenance, access }: { maintenance: unknown; access: AccessReport }) =>
+  maintenance === true && !holds(access, 'screen.dashboard') && !holds(access, 'enrollments.others')
+
+/** A localized value, such as a tag's name, in the viewer's locale, else any locale it holds. */
+export const inLocale = (value: unknown, locale: string): string | undefined => {
+  if (typeof value === 'string') return value
+  if (!value || typeof value !== 'object') return undefined
+  const held = value as Record<string, unknown>
+  const own = held[locale]
+  return typeof own === 'string' && own ? own : Object.values(held).find((one): one is string => typeof one === 'string' && !!one)
+}

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

@@ -0,0 +1,194 @@
+// The portal's frame, its own look apart from the dashboard's: the organization's name at its head, which is the
+// site's name in every locale, the portal's three places as pills across the top from md up and as a tab bar at
+// the foot of a phone, and one column between them. Its colors are the shadcn tokens the primitives read, set
+// here to the portal's teal and amber for each theme, so a Button or a Card inside it is the portal's without a
+// class of its own.
+import '@fontsource-variable/bricolage-grotesque'
+import { use, useState, type ReactNode } from 'react'
+import { BookOpen, ClipboardCheck, House, Wrench, type LucideIcon } from 'lucide-react'
+// add-on: settings
+import { useQuery } from '@tanstack/react-query'
+import type { Row } from 'mithaq/admin'
+import { useClient } from 'mithaq/admin/react'
+// end add-on: settings
+import type { NavEntry, ShellProps } from 'mithaq/admin'
+import { ScreenContext, useAccess, useLocale, useNav, useScreen, useUser } from 'mithaq/admin/react'
+import { holds } from 'mithaq/admin'
+import { currentOf } from 'mithaq-admin/nav-links.tsx'
+import { DiscardDialog } from 'mithaq-admin/discard-dialog.tsx'
+import { SidebarProvider } from '@/components/ui/sidebar'
+import { locales, switchLocale } from '@/copy.ts'
+import { frame, UserMenu } from '@asas/mithaq/ui/app-shell.tsx'
+import { navLabel } from '@asas/mithaq/ui/screen-nav.tsx'
+import { nameIn } from '@asas/mithaq/mithaq/auth/organizations.ts'
+// add-on: settings
+import { closedTo } from './rules.ts'
+// end add-on: settings
+
+export const regions = ['header', 'main'] as const
+
+/**
+ * The portal's colors over shadcn's tokens, light and dark. Teal is the brand, amber its accent; each pair is
+ * 4.5:1 or more, text on its ground.
+ */
+const tokens = [
+  '[--background:#F5F5F0] [--foreground:#1B1F24] [--card:#FFFFFF] [--card-foreground:#1B1F24]',
+  '[--primary:#0F6E6E] [--primary-foreground:#FFFFFF] [--ring:#0F6E6E] [--muted-foreground:#555A60]',
+  '[--accent:#EAF3F2] [--accent-foreground:#0F6E6E] [--border:#E4E4DC] [--input:#D9D9D0] [--portal-amber:#E8A33D]',
+  'dark:[--background:#0E1414] dark:[--foreground:#ECEFEE] dark:[--card:#172020] dark:[--card-foreground:#ECEFEE]',
+  'dark:[--primary:#5FB8B3] dark:[--primary-foreground:#0B2524] dark:[--ring:#5FB8B3] dark:[--muted-foreground:#A4B0AE]',
+  'dark:[--accent:#16312F] dark:[--accent-foreground:#9CD9D4] dark:[--border:#26302F] dark:[--input:#34403F] dark:[--portal-amber:#E8A33D]',
+].join(' ')
+
+/** The display face of the portal's headings. Its Latin is Bricolage Grotesque; Arabic falls to IBM Plex Sans Arabic. */
+export const display = "font-['Bricolage_Grotesque_Variable','IBM_Plex_Sans_Arabic',sans-serif] font-bold tracking-tight"
+
+const icons: Record<string, LucideIcon> = { '/': House, '/courses': BookOpen, '/enrollments': ClipboardCheck }
+
+// add-on: settings
+/** The organization's settings as the viewer reads them, or `null` where it may not or none are written yet. */
+const useSettings = () => {
+  const client = useClient()
+  return useQuery({
+    queryKey: ['portal-settings'],
+    queryFn: () => (client({ kayan: 'settings', operation: 'findOne', input: {} }) as Promise<Row | null>).catch(() => null),
+    staleTime: 60_000,
+  }).data
+}
+// end add-on: settings
+
+/** One place of the portal: its link, its label, and whether the viewer is on it. */
+const usePlaces = () => {
+  const { locale, t } = useLocale()
+  const screen = useScreen()
+  const access = useAccess()
+  const state = use(ScreenContext)
+  // A seat of anyone's is no longer the viewer's own, so the list is "My enrollments" only to a student.
+  const label = (entry: NavEntry) =>
+    entry.kayan === 'enrollments' && !holds(access, 'enrollments.others') ? t('portal.myEnrollments', 'My enrollments')! : navLabel({ entry, screen, locale, t })!
+  return [
+    { path: '/', href: screen.path, label: t('portal.home', 'Home')!, current: state?.path === screen.path },
+    ...useNav().map((entry) => ({ path: entry.path, href: `${screen.path}${entry.path}`, label: label(entry), current: currentOf(entry, state?.kayan?.name) === 'page' })),
+  ]
+}
+
+/** The other language, offered as its own name, so a reader who cannot read this one still finds theirs. */
+function LocaleButton() {
+  const { locale } = useLocale()
+  const other = locales.find((one) => one !== locale) ?? locale
+  // Asked first, in the app's discard dialog, where a form holds a change nobody saved.
+  const [asked, setAsked] = useState(false)
+  const { t } = useLocale()
+  return (
+    <>
+      <button
+        type="button"
+        lang={other}
+        aria-label={other === 'ar' ? 'العربية' : 'English'}
+        onClick={() => (window.onbeforeunload ? setAsked(true) : switchLocale({ to: other }))}
+        className="border-input bg-card text-foreground focus-visible:ring-ring inline-flex h-11 min-w-11 items-center justify-center rounded-full border px-3 text-sm focus-visible:ring-2 focus-visible:outline-none"
+      >
+        {other === 'ar' ? 'ع' : 'EN'}
+      </button>
+      <DiscardDialog open={asked} onOpenChange={setAsked} onDiscard={() => switchLocale({ to: other })} t={t} />
+    </>
+  )
+}
+
+/** What a student meets while the portal is closed for maintenance: why, and where to write meanwhile. */
+function Closed({ contact }: { contact?: string }) {
+  const { t } = useLocale()
+  return (
+    <section data-portal-closed="" className="bg-card mx-auto grid max-w-md justify-items-center gap-3 rounded-3xl px-6 py-12 text-center">
+      <Wrench aria-hidden className="text-primary size-10" />
+      <h1 className={`${display} text-2xl`}>{t('portal.closed', 'Closed for maintenance')}</h1>
+      <p className="text-muted-foreground">{t('portal.closedBody', 'The school is working on the portal. Please come back soon.')}</p>
+      {contact ? <Contact email={contact} /> : null}
+    </section>
+  )
+}
+
+function Contact({ email }: { email: string }) {
+  const { t } = useLocale()
+  return (
+    <p className="text-muted-foreground text-sm">
+      {t('portal.contact', 'Questions? Write to')}{' '}
+      <a href={`mailto:${email}`} dir="ltr" className="text-primary font-medium underline-offset-4 hover:underline">{email}</a>
+    </p>
+  )
+}
+
+export function PortalShell({ regions }: ShellProps<readonly ['header', 'main'], ReactNode>) {
+  const { locale, t } = useLocale()
+  const user = useUser()
+  const places = usePlaces()
+  // add-on: settings
+  const access = useAccess()
+  const settings = useSettings()
+  // The page answers what the viewer reads either way; this only draws the closed page in its place.
+  const closed = closedTo({ maintenance: settings?.maintenance, access })
+  const contact = typeof settings?.contactEmail === 'string' && settings.contactEmail ? settings.contactEmail : undefined
+  // end add-on: settings
+  // without add-on: settings
+  // const closed = false
+  // const contact: string | undefined = undefined
+  // end without add-on: settings
+  const active = user.organizations?.find((one) => one.id === user.activeOrganizationId)
+  const site = active ? nameIn(active, locale) : t('portal.title', 'Portal')!
+  const nav = t('portal.navigation', 'Portal')
+  return (
+    <SidebarProvider data-shell="top" data-portal="" style={frame} className={`bg-background text-foreground min-h-svh flex-col ${tokens}`}>
+      <header className="bg-card border-b">
+        <div className="mx-auto flex w-full max-w-6xl items-center justify-between gap-3 px-4 py-3 sm:px-6">
+          <a href={places[0]!.href} className="flex min-w-0 items-center gap-2.5 font-semibold">
+            <span aria-hidden className="bg-primary text-primary-foreground grid size-9 shrink-0 place-items-center rounded-[10px]">{[...site][0]}</span>
+            <span className="truncate">{site}</span>
+          </a>
+          <nav aria-label={nav} className="hidden gap-1 md:flex">
+            {places.map((place) => (
+              <a
+                key={place.path}
+                href={place.href}
+                aria-current={place.current ? 'page' : undefined}
+                className="text-foreground/80 hover:text-foreground aria-[current=page]:bg-accent aria-[current=page]:text-accent-foreground inline-flex h-11 items-center rounded-full px-4 text-[15px] aria-[current=page]:font-semibold"
+              >
+                {place.label}
+              </a>
+            ))}
+          </nav>
+          <div className="flex shrink-0 items-center gap-2">
+            <LocaleButton />
+            {/* The avatar alone: the menu signs out and switches locale too. */}
+            <div className="w-12 [&_[data-slot=avatar]]:grayscale-0 [&_[data-slot=avatar-fallback]]:bg-(--portal-amber) [&_[data-slot=avatar-fallback]]:text-[#1B1F24]">
+              <UserMenu />
+            </div>
+          </div>
+        </div>
+      </header>
+      <main data-region="main" className="mx-auto grid w-full max-w-6xl grid-cols-[minmax(0,1fr)] content-start gap-6 px-4 pt-6 pb-28 sm:px-6 md:pb-12">
+        {closed ? <Closed contact={contact} /> : <><div data-region="header">{regions.header}</div>{regions.main}</>}
+      </main>
+      {contact && !closed ? (
+        <footer className="mx-auto w-full max-w-6xl px-4 pb-28 sm:px-6 md:pb-8">
+          <Contact email={contact} />
+        </footer>
+      ) : null}
+      <nav aria-label={nav} className="bg-card fixed inset-x-0 bottom-0 z-10 grid grid-cols-3 border-t px-2 pt-1.5 pb-[max(env(safe-area-inset-bottom),0.75rem)] md:hidden">
+        {places.map((place) => {
+          const Icon = icons[place.path] ?? BookOpen
+          return (
+            <a
+              key={place.path}
+              href={place.href}
+              aria-current={place.current ? 'page' : undefined}
+              className="text-muted-foreground aria-[current=page]:text-primary flex min-h-13 flex-col items-center justify-center gap-1 text-xs aria-[current=page]:font-semibold"
+            >
+              <Icon aria-hidden className="size-[22px]" />
+              {place.label}
+            </a>
+          )
+        })}
+      </nav>
+    </SidebarProvider>
+  )
+}

package/template/templates/features/courses/sessions/seats.ts

@@ -0,0 +1,42 @@
+import { sql } from 'mithaq/drizzle'
+import type { NodePgDatabase } from 'mithaq/drizzle/node-postgres'
+import { serverTargets } from '@asas/mithaq'
+
+/** A write's transaction, which is drizzle's here. */
+const txOf = (tx: unknown) => tx as NodePgDatabase
+
+/**
+ * How many seats of a session are held, a withdrawn one not among them. Counted through the store, past the
+ * reader's own access, which a student's narrows to its own seat: a caller reads the session under that access first.
+ */
+export const seatsTaken = async ({ session, tx }: { session: string; tx?: unknown }) =>
+  (await serverTargets.drizzle.find({
+    tx,
+    kayan: 'enrollments',
+    args: { limit: 1, page: 1, sort: { field: 'id', direction: 'asc' }, where: { and: [{ session: { equals: session } }, { deletedAt: { exists: false } }] } },
+  })).totalDocs
+
+/**
+ * Serializes every write that takes a seat in one session until its transaction ends: a second write waits here,
+ * and under Read Committed its count, a statement after the lock, sees what the first one committed, so two
+ * writes never both take the last seat.
+ */
+export const holdSeats = async ({ tx, session }: { tx: unknown; session: string }) => {
+  await txOf(tx).execute(sql`select pg_advisory_xact_lock(hashtext('mithaq.seats'), hashtext(${session}))`)
+}
+
+/**
+ * What a seat is judged by, read off the columns in the write's transaction rather than through the actor's
+ * projection: a role shown no capacity, start or archived mark would otherwise read none and skip each rule. A
+ * caller reads the session under the actor's access first, so this reads only a session the actor may reach. Its
+ * `id` is the stored one, the same in every case the caller wrote it. Both rows stay locked before the
+ * enrollment's reference check, so an archive or capacity change cannot pass the decision, and the later
+ * `FOR KEY SHARE` does not require a lock upgrade. `FOR SHARE` lets enrollments share those rows while
+ * holding off their changes; `holdSeats` serializes the seat count for a session with a capacity.
+ *
+ * The tables and columns are written out, as the drizzle target names them; a rename fails R7a, R7b and R7f.
+ */
+export const sessionHeld = async ({ tx, session }: { tx: unknown; session: string }) =>
+  (await txOf(tx).execute<{ id: string; capacity: number | null; startsAt: Date; archived: boolean | null; courseArchived: boolean | null; selfEnroll: boolean | null }>(sql`
+    select s.id, s.capacity::float8 as capacity, s.starts_at as "startsAt", s.archived, c.archived as "courseArchived", c.self_enroll as "selfEnroll"
+    from course_sessions s join courses c on c.id = s.course_id where s.id = ${session} for share of s, c`)).rows[0]

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

@@ -0,0 +1,186 @@
+import { defaultFields, defaultOperations, type Ctx, type Where } from 'mithaq'
+import { defineKayan, organization } from '@asas/mithaq'
+import { activity, appPage, danger, backofficeList, backofficeRecord } from '@asas/mithaq/mithaq/pages.ts'
+import { courses, runsCatalogue } from '../courses/courses.ts'
+import { archivedRow, marks, reason, reasonInput, unarchived } from '../domain/archive.ts'
+
+/**
+ * Hands each matched session's `archive` no reason and nothing else, whatever the call sent as
+ * `data`, so the course page's bulk Archive can only archive, never un-archive.
+ */
+const archiveAll = (ctx: Ctx): Ctx => ({ ...ctx, data: { ...ctx.data, data: { reason: '' } } })
+
+/**
+ * What a session's create and edit pages both draw, written once so the two cannot drift. The edit
+ * page keeps the course on the side; the create page puts it first in the form, because it is
+ * required and a side column sits after Save.
+ */
+const details = [
+  { section: 'schedule', label: { en: 'Schedule', ar: 'الموعد' }, fields: [{ row: ['startsAt', 'capacity'] }] },
+  { section: 'place', label: { en: 'Venue and format', ar: 'المكان والصيغة' }, fields: [{ row: ['venue', 'format'] }] },
+  { section: 'notes', label: { en: 'Notes', ar: 'ملاحظات' }, fields: ['details'] },
+] as const
+const course = { section: 'course', label: { en: 'Course', ar: 'الدورة' }, fields: ['course'] } as const
+
+/**
+ * A session an actor reads, inside its active organization: one whose course that
+ * actor reads. Whoever runs the catalogue reads every session; a student or an instructor reads a
+ * session only when its course is published and not archived, and never the date of one it may not
+ * open.
+ */
+const ofReadableCourses = ({ user }: { user: unknown }): true | Where =>
+  runsCatalogue(user)
+    ? true
+    : { and: [{ 'course._status': { equals: 'published' } }, { or: [{ 'course.archived': { exists: false } }, { 'course.archived': { equals: false } }] }] }
+
+export const sessions = defineKayan({
+  name: 'sessions',
+  // ANDed with the inherited rows, so it narrows and never widens.
+  access: { read: ofReadableCourses },
+  // Better Auth owns a table named `session`, and `session` beside `sessions` in
+  // one schema is a trap.
+  dbName: 'course_sessions',
+  targets: {
+    backoffice: {
+      useAsTitle: 'startsAt',
+      pages: {
+        ...backofficeList('/sessions', { columns: ['startsAt', 'organization', 'course', 'capacity', 'venue'], filters: ['organization', 'course', 'venue', 'archived'], search: ['venue', 'course.title'], sort: '-startsAt' }),
+        ...backofficeRecord({
+          path: '/sessions/:id',
+          main: [{ tabs: [
+            { tab: 'details', label: { en: 'Details', ar: 'التفاصيل' }, fields: [
+              { section: 'schedule', label: { en: 'Schedule', ar: 'الموعد' }, fields: [{ row: ['startsAt', 'capacity'] }] },
+              { section: 'place', label: { en: 'Venue and format', ar: 'المكان والصيغة' }, fields: [{ row: ['venue', 'format'] }] },
+              { section: 'notes', label: { en: 'Notes', ar: 'ملاحظات' }, fields: ['details'] },
+            ] },
+            { tab: 'enrollments', label: { en: 'Enrollments', ar: 'التسجيلات' }, fields: [{ list: { of: 'enrollments', where: 'session', columns: ['student', 'createdAt'] } }] },
+          ] }],
+          side: [{ section: 'course', label: { en: 'Course', ar: 'الدورة' }, fields: ['course', 'archived'] }],
+        }),
+      },
+    },
+    // The portal lists sessions for this alone: an enrollment's session reads by its start there as it
+    // does on the dashboard.
+    portal: { useAsTitle: 'startsAt' },
+    dashboard: {
+      // What a session is shown by wherever it stands for itself: the picker on `enrollments.session`
+      // and a relationship column pointing here. A session declares no name, and its start tells two
+      // sessions of one course apart, drawn in the viewer's own format. The search boxes come to
+      // nothing, because `like` takes text and email.
+      useAsTitle: 'startsAt',
+      description: {
+        en: 'The dates each course meets, and how many seats each one holds.',
+        ar: 'مواعيد انعقاد كل دورة، وعدد المقاعد في كل منها.',
+      },
+      pages: {
+        list: { path: '/sessions', page: appPage([{ layout: 'table', main: [{ list: {
+          columns: ['course', 'startsAt', 'capacity', 'venue'],
+          filters: ['course', 'startsAt', 'venue', 'format', 'archived'],
+          search: ['course.title', 'details'],
+        } }] }]) },
+        create: {
+          path: '/sessions/new',
+          page: appPage([{ layout: 'record', main: [{ form: [course, ...details] }] }]),
+        },
+        edit: {
+          path: '/sessions/:id',
+          page: appPage([{
+            layout: 'record',
+            main: [{ tabs: [
+              { tab: 'details', label: { en: 'Details', ar: 'التفاصيل' }, fields: [{ form: details }] },
+              // Drawn only for an actor the report lets read them: a tab whose only node is hidden is not
+              // drawn, so a registrar is not shown a tab with nothing in it.
+              { tab: 'enrollments', label: { en: 'Enrollments', ar: 'التسجيلات' }, fields: [{ list: {
+                of: 'enrollments',
+                where: 'session',
+                columns: ['student', 'createdAt'],
+              }, when: { '$user.collections.enrollments.operations.find': { equals: true } } }] },
+            ] }],
+            // Whether it is archived and why, read only: a session is archived through its own operations.
+            side: [{ ...course, fields: [...course.fields, { field: 'archived', readOnly: true }, { field: 'archiveReason', readOnly: true }] }, activity],
+            // Archived and brought back as a course is, each with its reason, before the delete.
+            danger: danger({
+              button: 'archive',
+              when: unarchived,
+              label: { en: 'Archive', ar: 'أرشفة' },
+              fields: ['reason'],
+              reload: true,
+              confirm: { title: { en: 'Archive this session?', ar: 'أرشفة هذه الجلسة؟' }, body: { en: 'It stays on the course, marked archived.', ar: 'تبقى في الدورة، معلمة بأنها مؤرشفة.' } },
+            }, {
+              button: 'unarchive',
+              when: archivedRow,
+              label: { en: 'Unarchive', ar: 'إلغاء الأرشفة' },
+              fields: ['reason'],
+              reload: true,
+              confirm: { title: { en: 'Unarchive this session?', ar: 'إلغاء أرشفة هذه الجلسة؟' }, body: { en: 'It is open again as it was.', ar: 'تعود مفتوحة كما كانت.' } },
+            }),
+          }]),
+        },
+      },
+    },
+    service: {
+      operations: {
+        ...defaultOperations,
+        // One `archive` per matched row under the same access, so the mark is written by an
+        // archive alone.
+        archiveMany: { each: 'archive', steps: ({ steps }) => [archiveAll, steps.updateMany] },
+        archive: {
+          targets: { dashboard: { fields: { reason } } },
+          input: () => reasonInput('sessions.operations.archive'),
+          steps: ({ steps }) => [marks(true), steps.update],
+        },
+        unarchive: {
+          targets: { dashboard: { fields: { reason } } },
+          input: () => reasonInput('sessions.operations.unarchive'),
+          steps: ({ steps }) => [marks(false), steps.update],
+        },
+      },
+    },
+  },
+  fields: {
+    ...defaultFields,
+    organization,
+    course: {
+      kind: 'relationship',
+      label: { en: 'Course', ar: 'الدورة' },
+      relationTo: () => courses,
+      rules: { required: true },
+    },
+    startsAt: { kind: 'datetime', label: { en: 'Starts at', ar: 'وقت البداية' }, rules: { required: true } },
+    // A session with room for nobody is not a session, so one is the floor.
+    capacity: { kind: 'number', label: { en: 'Capacity', ar: 'السعة' }, rules: { min: 1 } },
+    venue: {
+      kind: 'text', label: { en: 'Venue', ar: 'المكان' },
+      options: [
+        { value: 'online', label: { en: 'Online', ar: 'عبر الإنترنت' } },
+        { value: 'campus', label: { en: 'Campus', ar: 'الحرم' } },
+      ],
+      targets: { dashboard: { component: 'nativeSelect' } },
+    },
+    format: {
+      kind: 'text', label: { en: 'Format', ar: 'الصيغة' },
+      options: [
+        { value: 'workshop', label: { en: 'Workshop', ar: 'ورشة عمل' } },
+        { value: 'lecture', label: { en: 'Lecture', ar: 'محاضرة' } },
+      ],
+      targets: { dashboard: { component: 'combobox' } },
+    },
+    // Written by `archive` and `unarchive` alone, as a course's is, and `archiveMany` runs an archive per row.
+    archived: { kind: 'checkbox', label: { en: 'Archived', ar: 'مؤرشفة' }, rules: { providedBy: { create: 'never', update: 'application' } } },
+    details: { kind: 'richText', label: { en: 'Details', ar: 'التفاصيل' } },
+    /**
+     * The enrollments that point at this session: the one kind that builds no column. `enrollments.session`
+     * holds this row's id, so a read populates the array through the enrollments kayan's own access and
+     * soft-delete filter, and a read that names no `depth` populates none of it.
+     */
+    enrollments: {
+      kind: 'join',
+      relationTo: 'enrollments',
+      on: 'session',
+      label: { en: 'Enrollments', ar: 'التسجيلات' },
+    },
+    // Why it was last archived or brought back. Declared last, so a pushed table and a migrated one
+    // hold the column in the same place.
+    archiveReason: { kind: 'text', label: { en: 'Archive reason', ar: 'سبب الأرشفة' }, rules: { maxLength: 200, providedBy: { create: 'never', update: 'application' } } },
+  },
+})

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

@@ -0,0 +1,10 @@
+import { media, type ImageRead } from './media/media.ts'
+
+export type { ImageRead }
+
+/**
+ * The feature's kayan, built for the reads beside `media.create` that open an
+ * image, which each feature whose rows point at images brings and the asas
+ * hands in. With none, only a holder of `media.create` reads an image.
+ */
+export const kayan = ({ reads }: { reads: readonly ImageRead[] }) => [media({ reads })] as const

package/template/templates/features/media/media/media.ts

@@ -0,0 +1,131 @@
+import { defaultFields, defaultOperations, folderOf, uploadFields, withUploadReference, type Where } from 'mithaq'
+import { defineKayan, organization } from '@asas/mithaq'
+import { readsPast } from '@asas/mithaq/roles/tenant-access.ts'
+import { appPage, danger } from '@asas/mithaq/mithaq/pages.ts'
+import { storageConfig } from '@asas/mithaq/storage/index.ts'
+
+const ui = folderOf(new URL('./ui/', import.meta.url))
+
+/**
+ * One way an actor that holds no `media.create` reads an image: the images it
+ * may read, or `false` for none. Never `true`, which would open every image of
+ * the organization to whoever the read answered it for.
+ */
+export type ImageRead = (args: { user: unknown }) => Promise<Where | false>
+
+/**
+ * The images an actor reads, inside its active organization: every image of
+ * its organization where it holds `media.create`, and otherwise only those one
+ * of `reads` answers. `media.create` is the line because a role that adds
+ * images has to find one before anything names it, in an upload field's
+ * picker. A file at `GET /api/media/file/<id>` is read through this kayan's
+ * own `findByID`, so the same answer decides who downloads it.
+ */
+const imagesReadBy = (reads: readonly ImageRead[]) => async ({ user }: { user: unknown }) => {
+  if (readsPast(user, 'media.create')) return true
+  const answered: unknown[] = await Promise.all(reads.map((read) => read({ user })))
+  // The type forbids it, but a cast `true` or a filter of nothing would open every image of the
+  // organization, so either throws and the actor reads none.
+  for (const [at, answer] of answered.entries()) {
+    if (answer !== false && (!answer || typeof answer !== 'object' || !Object.keys(answer).length)) {
+      throw new Error(`The image read ${reads[at]!.name || `at ${at}`} answered ${JSON.stringify(answer)}, which would open every image; a read answers false or a filter.`)
+    }
+  }
+  const answers = answered.filter((one): one is Where => one !== false)
+  if (!answers.length) return false
+  return answers.length === 1 ? answers[0]! : { or: answers }
+}
+
+/**
+ * The organization's images: a row per file, whose object is kept where the
+ * project's storage puts it. An upload field points at one, as a course's cover does.
+ *
+ * It spreads `uploadFields`, the columns the create writes from the upload it
+ * verified and nobody writes after, and declares its own create and delete:
+ * the create takes the signed `uploadReference` that
+ * `POST /api/media/uploadInstructions` handed out and runs the project's
+ * `uploaded`, and the delete runs its `removed` after the commit. `buildAsas`
+ * refuses a create that skips the configured `uploaded`. A file is
+ * read at `GET /api/media/file/<id>` through this kayan's own `findByID`, so
+ * its organization and `reads` decide who reads it. It keeps no versions, since a file never changes once it is
+ * made; a kayan pointing at one keeps the versions of that pointer instead.
+ */
+export const media = ({ reads }: { reads: readonly ImageRead[] }) => defineKayan({
+  name: 'media',
+  // ANDed with the inherited rows, so it narrows and never widens.
+  access: { read: imagesReadBy(reads) },
+  messages: {
+    singular: { en: 'Image', ar: 'صورة' },
+    plural: { en: 'Images', ar: 'الصور' },
+  },
+  targets: {
+    storage: { mimeTypes: ['image/png', 'image/jpeg', 'image/webp'] },
+    // A file is named by its name wherever it stands for itself: the upload
+    // control's picker and a relationship column pointing here.
+    portal: { useAsTitle: 'filename' },
+    // The organization's images, listed and re-described. A file is made
+    // where it is used, by the upload control, and on this kayan's own New
+    // page, both through the upload dialog, which sends it before the row is
+    // made. The list draws each image's thumbnail beside its name and its size as a
+    // person reads it. The file's own columns are the runner's, so the edit
+    // page draws them read-only, with the image, its size, Download and
+    // Replace file beside the form, and above it on a phone.
+    dashboard: {
+      useAsTitle: 'filename',
+      description: { en: 'The images this organization uses, each with the words a screen reader says for it.', ar: 'الصور التي تستخدمها هذه المؤسسة، ولكل منها الكلمات التي يقرؤها قارئ الشاشة.' },
+      pages: {
+        list: { path: '/media', page: appPage([{ layout: 'table', main: [{ list: {
+          columns: [{ field: 'filename', cell: ui('preview.tsx#FileName') }, 'alt', 'mimeType', { field: 'filesize', cell: ui('preview.tsx#FileSize') }, 'createdAt'],
+          search: ['filename'],
+          sort: '-createdAt',
+        } }] }]) },
+        create: { path: '/media/new', component: ui('preview.tsx#NewImage') },
+        edit: {
+          path: '/media/:id',
+          page: appPage([{
+            layout: 'record',
+            main: [{ form: [
+              { section: 'description', label: { en: 'Description', ar: 'الوصف' }, fields: ['alt'] },
+              { section: 'file', label: { en: 'File', ar: 'الملف' }, fields: ['filename', 'mimeType', { row: ['width', 'height'] }] },
+            ] }],
+            side: [{ component: ui('preview.tsx#MediaPreview') }],
+            danger: danger(),
+          }]),
+        },
+      },
+    },
+    service: {
+      operations: {
+        ...defaultOperations,
+        // The upload inside the create. Before the transaction opens, the
+        // signed reference is checked and the stored object is read back,
+        // and every file column is written from what the server measured.
+        // Then the row is made in one insert.
+        create: {
+          ...defaultOperations.create,
+          input: ({ create }) => withUploadReference(create),
+          beforeTransaction: [storageConfig.uploaded],
+        },
+        // The object is removed only once the row's removal has committed,
+        // so a failure leaves an orphan for the sweep and never a row that
+        // names nothing.
+        delete: {
+          ...defaultOperations.delete,
+          afterCommit: ({ afterCommit }) => [...afterCommit, storageConfig.removed],
+        },
+      },
+    },
+  },
+  fields: {
+    ...defaultFields,
+    organization,
+    ...uploadFields,
+    // What a screen reader says for the image, in every locale, since an
+    // image with no words is no image to someone who cannot see it.
+    alt: {
+      kind: 'text',
+      label: { en: 'Alternative text', ar: 'النص البديل' },
+      rules: { localized: true, required: true, maxLength: 300 },
+    },
+  },
+})