create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/asas/src/ui-dashboard/theme-provider.tsx

@@ -0,0 +1,10 @@
+// The dashboard screen's one provider, folded around its shell: it marks the
+// subtree the screen draws, so a stylesheet can scope to it.
+import type { ReactNode } from 'react'
+import type { ProviderProps } from 'mithaq/admin'
+
+export const ThemeProvider = ({ children }: ProviderProps<ReactNode>) => (
+  <div data-provider="theme" className="contents">
+    {children}
+  </div>
+)

package/template/templates/asas/src/ui-dashboard/versions.tsx

@@ -0,0 +1,446 @@
+// The versions are read in the browser, as the viewer, from the kayan's own
+// `findVersions`, which answers only the versions of rows the viewer reads, each
+// cut to the columns it reads. The page draws this only for an actor holding that
+// key, and the restore only for one holding `restoreVersion`; the server refuses
+// either to anyone else whatever the page drew.
+import { useContext, useEffect, useMemo, useState } from 'react'
+import { same, type ClientField, type ComponentProps, type Row } from 'mithaq/admin'
+import { FormContext, useAccess, useClient, useKayan, useLocale, useRecord, useScreen } from 'mithaq/admin/react'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog'
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Checkbox } from '@/components/ui/checkbox'
+import { Label } from '@/components/ui/label'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Sheet, SheetClose, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet'
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table'
+import { blocksOf, richTextPlainText } from 'mithaq-admin/rich-text-line.ts'
+import { cellFor, useComponents } from 'mithaq-admin/components.tsx'
+import type { FindApi, FoundPage } from 'mithaq-admin/control-props.ts'
+import { labelFor, titleOf } from 'mithaq-admin/copy.ts'
+import { formatDate } from 'mithaq-admin/format.tsx'
+import { doneWords } from 'mithaq-admin/form-rules.tsx'
+import { carry } from 'mithaq-admin/toast.tsx'
+import { refusalKeyOf } from 'mithaq-admin/refusal.ts'
+import { endonym } from 'mithaq-admin/locale-menu.ts'
+import { CloseButton } from 'mithaq-admin/record-frame.tsx'
+import { useRelationshipTitles } from 'mithaq-admin/relationship-cell.tsx'
+
+/**
+ * What a version's column draws as a dash: absent, `null`, an empty string or
+ * an empty list, as the audit log's activity panel reads it. Its own here, so a
+ * project without the audit log keeps its versions.
+ */
+const empty = (value: unknown) => value === undefined || value === null || value === '' || (Array.isArray(value) && !value.length)
+
+/** One version as `findVersions` answers it. */
+export type Version = {
+  id: string
+  latest: boolean
+  autosave: boolean
+  updatedAt: string | Date
+  version: Row
+}
+
+/** How many versions one read asks for, and how many more each "Show older" adds. */
+const page = 10
+
+/** The four status labels, each under its `version` key with the English it falls back to. */
+const labels = {
+  currentDraft: 'Current draft',
+  draft: 'Draft',
+  currentlyPublished: 'Currently published',
+  previouslyPublished: 'Previously published',
+} as const
+
+/**
+ * Which of the four labels a version wears, over the row's versions newest first.
+ * A draft is the current draft when it is the latest version, since then no
+ * published version is newer than it. A published version is the currently
+ * published one when it is the newest published version: the row always holds the
+ * last published copy and nothing unpublishes it. The newest page is always read
+ * first, so that version is on it whenever any published version is.
+ */
+const labelOf = (version: Version, versions: readonly Version[]): keyof typeof labels | undefined =>
+  // A reader without the `_status` column gets it cut from every version, and
+  // a status nobody can read is no status to draw.
+  !('_status' in version.version)
+    ? undefined
+    : version.version._status === 'draft'
+      ? version.latest ? 'currentDraft' : 'draft'
+      : version.id === versions.find((one) => one.version._status !== 'draft')?.id ? 'currentlyPublished' : 'previouslyPublished'
+
+/** The columns every kayan of this project carries and no person edits, and the status the pill already says. */
+const technical = new Set(['id', 'organization', 'createdAt', 'updatedAt', '_status'])
+
+/**
+ * The words of each block of `side`, and whether `other` holds no block of the
+ * same value, as a block is the unit a person reads a rich text change by. A block
+ * is held by its whole value, so one whose format or link changed is marked though
+ * its words did not.
+ */
+const changedBlocks = ({ side, other }: { side: unknown; other: unknown }) => {
+  const left = new Map<string, number>()
+  for (const block of blocksOf(other)) {
+    const key = JSON.stringify(block)
+    left.set(key, (left.get(key) ?? 0) + 1)
+  }
+  return blocksOf(side).flatMap((block) => {
+    const key = JSON.stringify(block)
+    const held = left.get(key) ?? 0
+    if (held) left.set(key, held - 1)
+    const text = richTextPlainText(block).trim()
+    return text ? [{ text, changed: held === 0 }] : []
+  })
+}
+
+const entriesOf = (value: unknown) => (value && typeof value === 'object' && !Array.isArray(value) ? Object.keys(value) : [])
+
+/**
+ * The panel an edit page names as a component node. It reads the row the page
+ * draws and its kayan off the screen, so one file serves every kayan that keeps
+ * drafts.
+ */
+export function Versions(_: ComponentProps) {
+  const { t, locale } = useLocale()
+  const kayan = useKayan()
+  const record = useRecord()
+  const client = useClient()
+  const id = record?.id === undefined ? undefined : String(record.id)
+  // How many saves have landed on the form this panel sits in, an autosave
+  // included. A draft save never moves the row's own `updatedAt`, so this is what
+  // tells a panel that stayed mounted through one that its list is stale.
+  const saves = useContext(FormContext)?.saves ?? 0
+  // The row as this page last drew it: a save moves its `updatedAt` or bumps
+  // `saves`, and the panel reads its versions again.
+  const seen = `${id}@${String(record?.updatedAt ?? '')}@${saves}`
+  const [limit, setLimit] = useState(page)
+  const [read, setRead] = useState<{ seen: string; docs: Version[]; more: boolean } | { seen: string; failed: true }>()
+  const [opened, setOpened] = useState<Version>()
+
+  // The client is left out of the dependencies: the host makes a new one on every
+  // render, so following it would read the same page again on every render.
+  useEffect(() => {
+    if (!id) return
+    let live = true
+    ;(client({ kayan: kayan.name, operation: 'findVersions', input: { where: { parent: { equals: id } }, sort: '-updatedAt', limit } }) as Promise<{ docs: Version[]; hasNextPage: boolean }>).then(
+      (found) => live && setRead({ seen, docs: found.docs, more: found.hasNextPage }),
+      () => live && setRead({ seen, failed: true }),
+    )
+    return () => {
+      live = false
+    }
+  }, [kayan.name, seen, limit])
+
+  const shown = read?.seen === seen ? read : undefined
+  const when = (at: string | Date) => formatDate({ value: at, locale }) ?? String(at)
+  return (
+    <div data-panel="versions" className="grid gap-4">
+      {shown === undefined ? (
+        <p className="text-muted-foreground text-sm">{t('version.loading', 'Loading versions…')}</p>
+      ) : 'failed' in shown ? (
+        <p role="alert" className="text-destructive text-sm">{t('version.failed', 'The versions could not be read.')}</p>
+      ) : !shown.docs.length ? (
+        <p className="text-muted-foreground text-sm">{t('version.none', 'No versions yet.')}</p>
+      ) : (
+        <>
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>{t('version.updatedAt', 'Updated at')}</TableHead>
+                <TableHead>{t('version.status', 'Status')}</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {shown.docs.map((version) => (
+                <TableRow key={version.id} data-version={version.id}>
+                  <TableCell>
+                    {/* Underlined and in the link colour at rest, since a phone has
+                        no hover to show that the date opens the comparison, and
+                        44 pixels tall. */}
+                    <button type="button" data-button="open-version" className="text-primary inline-flex min-h-11 cursor-pointer items-center underline underline-offset-4" onClick={() => setOpened(version)}>
+                      <time dateTime={new Date(version.updatedAt).toISOString()}>{when(version.updatedAt)}</time>
+                    </button>
+                  </TableCell>
+                  <TableCell>
+                    <div className="flex flex-wrap gap-1">
+                      {version.autosave ? <Badge variant="outline">{t('version.autosave', 'Autosave')}</Badge> : null}
+                      <Pill version={version} versions={shown.docs} />
+                    </div>
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+          {shown.more ? (
+            <Button type="button" variant="outline" size="sm" onClick={() => setLimit(limit + page)}>
+              {t('version.more', 'Show older')}
+            </Button>
+          ) : null}
+          {opened && id ? <Compare key={opened.id} version={opened} versions={shown.docs} parent={id} onClose={() => setOpened(undefined)} /> : null}
+        </>
+      )}
+    </div>
+  )
+}
+
+/** A version's status pill, the currently published one standing out. */
+function Pill({ version, versions }: { version: Version; versions: readonly Version[] }) {
+  const { t } = useLocale()
+  const label = labelOf(version, versions)
+  return label ? <Badge variant={label === 'currentlyPublished' ? 'default' : 'outline'}>{t(`version.${label}`, labels[label])}</Badge> : null
+}
+
+/**
+ * The sheet over the list: the version, and the one it is compared against, by
+ * default the newest one older than it, field by field, each value drawn by the
+ * field's own cell and a localized field one row per locale, modified fields only
+ * until the viewer asks for all. A column the viewer may not read is in neither
+ * snapshot, so it draws no row.
+ */
+function Compare({ version, versions, parent, onClose }: { version: Version; versions: readonly Version[]; parent: string; onClose: () => void }) {
+  const { t, locale, dir } = useLocale()
+  const kayan = useKayan()
+  const client = useClient()
+  const screen = useScreen()
+  const restores = useAccess().collections?.[kayan.name]?.operations?.restoreVersion === true
+  /** Whether the kayan's restore takes `expectedUpdatedAt`, as the form this panel sits in says. */
+  const takes = useContext(FormContext)?.expectedUpdatedAtOn?.includes('restoreVersion') === true
+  /** The version compared against, or `''` for the one before. */
+  const [against, setAgainst] = useState('')
+  const [modifiedOnly, setModifiedOnly] = useState(true)
+  /** The version before this one, read once: the list holds every other version a person may pick. */
+  const [prior, setPrior] = useState<{ version: Version | null } | { failed: true }>()
+  /** The restore waiting on its confirm, and whether it restores as a draft. */
+  const [confirming, setConfirming] = useState<{ draft: boolean }>()
+  const [restoring, setRestoring] = useState(false)
+  /** A restore the server refused, drawn in the sheet, which stays open. */
+  const [restoreFailed, setRestoreFailed] = useState<unknown>(undefined)
+
+  useEffect(() => {
+    let live = true
+    const older = { and: [{ parent: { equals: parent } }, { updatedAt: { less_than: new Date(version.updatedAt).toISOString() } }] }
+    ;(client({ kayan: kayan.name, operation: 'findVersions', input: { where: older, sort: '-updatedAt', limit: 1 } }) as Promise<{ docs: Version[] }>).then(
+      (found) => live && setPrior({ version: found.docs[0] ?? null }),
+      () => live && setPrior({ failed: true }),
+    )
+    return () => {
+      live = false
+    }
+  }, [version.id])
+
+  const previous = prior && 'version' in prior ? prior.version : null
+  const from = against ? versions.find((one) => one.id === against) ?? null : previous
+  const rows = kayan.fields
+    .filter((field) => field.kind !== 'join' && !technical.has(field.name) && (field.name in version.version || (!!from && field.name in from.version)))
+    .flatMap((field): { key: string; field: ClientField; before: unknown; after: unknown; code?: string }[] => {
+      const before = from?.version[field.name]
+      const after = version.version[field.name]
+      if (field.rules.localized !== true) return [{ key: field.name, field, before, after }]
+      // Each locale's value alone, drawn by the field's cell as a plain value.
+      const plain: ClientField = { ...field, rules: { ...field.rules, localized: false } }
+      const codes = [...new Set([...entriesOf(before), ...entriesOf(after)])]
+      return codes.map((code) => ({
+        key: `${field.name}.${code}`,
+        field: plain,
+        before: (before as Record<string, unknown> | undefined)?.[code],
+        after: (after as Record<string, unknown> | undefined)?.[code],
+        code,
+      }))
+    })
+    // Whether the two sides differ, once per row, which both the filter and the row's mark read.
+    .map((row) => ({ ...row, changed: !(same(row.before, row.after) || (empty(row.before) && empty(row.after))) }))
+    .filter((row) => !modifiedOnly || row.changed)
+
+  // Every kayan this screen crosses, so a relationship's value is named the way
+  // the list names it.
+  const kayans = useMemo(() => Object.values(screen.kayan), [screen])
+  const api = useMemo<FindApi>(
+    () => Object.fromEntries(kayans.map((one) => [one.name, { find: (input: Row) => client({ kayan: one.name, operation: 'find', input }) as Promise<FoundPage> }])),
+    [kayans],
+  )
+  const titles = useRelationshipTitles({ fields: kayan.fields, docs: [version.version, from?.version ?? {}], context: { api, client: kayans, locale } })
+  const { cells } = useComponents()
+  const copy = { t, locale }
+  // A rich text value whole, a block to a line, where its list cell draws the
+  // first block alone: a change further down would read as no change. A block the
+  // other side does not hold is marked, as removed (`del`) on the side compared
+  // against and as added (`ins`) on the side viewed: struck through and underlined
+  // as well as tinted, so the mark does not rest on colour alone.
+  const drawn = (field: ClientField, value: unknown, other: unknown, mark: 'del' | 'ins') => {
+    if (empty(value)) return '—'
+    if (field.kind !== 'richText') return cellFor({ cells, field })({ kayan, field, value, t, locale, titles })
+    const blocks = changedBlocks({ side: value, other })
+    // A value of images or empty blocks alone has no words, and reads as empty.
+    if (!blocks.length) return '—'
+    return blocks.map(({ text, changed }, at) => {
+      const Mark = mark
+      return <p key={at} dir="auto" className="whitespace-pre-line">{changed ? <Mark data-block-changed="" className={mark === 'del' ? 'bg-destructive/15 line-through' : 'bg-primary/15 underline'}>{text}</Mark> : text}</p>
+    })
+  }
+  const when = (at: string | Date) => formatDate({ value: at, locale }) ?? String(at)
+  const named = (one: Version) => {
+    const label = labelOf(one, versions)
+    return label ? `${when(one.updatedAt)} · ${t(`version.${label}`, labels[label])}` : when(one.updatedAt)
+  }
+  const options = [
+    // With its date, so the select says which version it compares against.
+    { value: '', label: previous ? `${t('version.previousVersion', 'Previous version')} · ${when(previous.updatedAt)}` : (t('version.previousVersion', 'Previous version') ?? '') },
+    // The version before is offered once, as "Previous version".
+    ...versions.filter((one) => one.id !== version.id && one.id !== previous?.id).map((one) => ({ value: one.id, label: named(one) })),
+  ]
+
+  /**
+   * Puts the version back, onto the row or as a new draft, and draws the page
+   * again from the server, so the form reads what the restore wrote. A refused or
+   * failed restore keeps the sheet open and draws its own sentence and the
+   * server's (`refusalKeyOf`, which the form's own banner reads the same way).
+   */
+  const restore = async (draft: boolean) => {
+    setRestoring(true)
+    setRestoreFailed(undefined)
+    try {
+      // The instant of the latest version this panel read, where the kayan's
+      // restore takes it, so a restore over a newer draft another person saved
+      // since is refused 409 rather than burying it.
+      const read = takes ? versions.find((one) => one.latest)?.version.updatedAt : undefined
+      await client({ kayan: kayan.name, operation: 'restoreVersion', input: { id: version.id, ...(read !== undefined && { expectedUpdatedAt: read }) }, draft })
+      carry(doneWords({ kayan, copy: { t, locale }, operation: { name: 'restoreVersion' } }))
+      window.location.reload()
+    } catch (thrown) {
+      setRestoring(false)
+      setConfirming(undefined)
+      setRestoreFailed(thrown)
+    }
+  }
+  const restoreFailedKey = restoreFailed === undefined ? undefined : refusalKeyOf(restoreFailed)
+
+  return (
+    <Sheet open onOpenChange={(open) => !open && onClose()}>
+      {/* The primitive's `data-[side=*]:w-3/4` is outranked by naming the same
+          side, so the sheet is the phone's whole width. */}
+      <SheetContent showCloseButton={false} side={dir === 'rtl' ? 'left' : 'right'} className="w-full overflow-y-auto data-[side=left]:w-full data-[side=right]:w-full data-[side=left]:sm:max-w-2xl data-[side=right]:sm:max-w-2xl">
+        <SheetHeader>
+          <SheetTitle>{t('version.compareVersions', 'Compare versions')}</SheetTitle>
+        </SheetHeader>
+        <div className="grid gap-4 px-4">
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div className="grid gap-1.5">
+              <span className="text-muted-foreground text-xs">{t('version.comparingAgainst', 'Comparing against')}</span>
+              <Select value={against} disabled={prior === undefined} onValueChange={(value) => setAgainst(String(value ?? ''))}>
+                <SelectTrigger className="w-full max-sm:data-[size=default]:h-11"><SelectValue>{options.find((one) => one.value === against)?.label}</SelectValue></SelectTrigger>
+                <SelectContent>
+                  {options.map((one) => (
+                    <SelectItem key={one.value} value={one.value}>{one.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </div>
+            <div className="grid gap-1.5">
+              <span className="text-muted-foreground text-xs">{t('version.currentlyViewing', 'Currently viewing')}</span>
+              <div className="flex flex-wrap items-center gap-1 text-sm">
+                <time dateTime={new Date(version.updatedAt).toISOString()}>{when(version.updatedAt)}</time>
+                {version.autosave ? <Badge variant="outline">{t('version.autosave', 'Autosave')}</Badge> : null}
+                <Pill version={version} versions={versions} />
+              </div>
+            </div>
+          </div>
+          <div className="flex items-center gap-2">
+            <Checkbox id={`${version.id}-modified-only`} data-modified-only checked={modifiedOnly} onCheckedChange={(checked) => setModifiedOnly(checked === true)} />
+            <Label htmlFor={`${version.id}-modified-only`}>{t('version.modifiedOnly', 'Modified only')}</Label>
+          </div>
+          {prior === undefined ? (
+            <p className="text-muted-foreground text-sm">{t('version.loading', 'Loading versions…')}</p>
+          ) : 'failed' in prior && !against ? (
+            <p role="alert" className="text-destructive text-sm">{t('version.failed', 'The versions could not be read.')}</p>
+          ) : !rows.length ? (
+            <p className="text-muted-foreground text-sm">{t('version.noReadableChange', 'No field you may read changed.')}</p>
+          ) : (
+            <ul className="grid gap-3 text-sm">
+              {/* Which side is which, over the two columns, since on a phone
+                  the two labels above stack in one. */}
+              <li aria-hidden="true" className="text-muted-foreground grid grid-cols-2 gap-2 text-xs">
+                <span>{t('version.comparingAgainst', 'Comparing against')}</span>
+                <span>{t('version.currentlyViewing', 'Currently viewing')}</span>
+              </li>
+              {rows.map((row) => {
+                // What the "Modified only" filter keeps, so with every field shown
+                // the rows that differ say so in words and in a rule at their start.
+                const { changed } = row
+                return (
+                  <li key={row.key} data-diff={row.key} data-changed={changed ? '' : undefined} className={changed ? 'border-primary grid gap-1 border-s-2 ps-2' : 'grid gap-1'}>
+                    <span className="flex items-center gap-1.5 font-medium">
+                      {labelFor({ kayan, field: row.field, copy })}
+                      {row.code ? <Badge variant="outline">{endonym(row.code)}</Badge> : null}
+                      {changed && !modifiedOnly ? <Badge data-badge="changed">{t('version.fieldChanged', 'Changed')}</Badge> : null}
+                    </span>
+                    <div className="grid grid-cols-2 gap-2">
+                      <div data-before className="bg-muted/50 min-w-0 rounded-md px-2 py-1 break-words">{drawn(row.field, row.before, row.after, 'del')}</div>
+                      <div data-after className="bg-muted min-w-0 rounded-md px-2 py-1 break-words">{drawn(row.field, row.after, row.before, 'ins')}</div>
+                    </div>
+                  </li>
+                )
+              })}
+            </ul>
+          )}
+          {restoreFailed !== undefined ? (
+            <>
+              <p role="alert" className="rounded-md border border-destructive/50 px-3 py-2 text-sm text-destructive">
+                {t('version.problemRestoringVersion', 'There was a problem restoring this version')}
+              </p>
+              {restoreFailedKey ? (
+                <p role="alert" className="rounded-md border border-destructive/50 px-3 py-2 text-sm text-destructive">
+                  {t(restoreFailedKey, restoreFailedKey)}
+                </p>
+              ) : null}
+            </>
+          ) : null}
+        </div>
+        {restores && labelOf(version, versions) !== 'currentlyPublished' ? (
+          // Not offered for the version the row already holds, where a restore would add a version and an
+          // activity line and change nothing. Sticky at the popup's foot, so Restore stays in reach however long the diff is.
+          <SheetFooter className="bg-inherit sticky bottom-0 flex-row flex-wrap justify-end border-t">
+            {'_status' in version.version && version.version._status !== 'draft' ? (
+              <Button type="button" variant="outline" className="max-sm:h-11" data-button="restore-as-draft" disabled={restoring} onClick={() => setConfirming({ draft: true })}>
+                {t('version.restoreAsDraft', 'Restore as draft')}
+              </Button>
+            ) : null}
+            <Button type="button" className="max-sm:h-11" data-button="restore" disabled={restoring} onClick={() => setConfirming({ draft: false })}>
+              {t('version.restoreThisVersion', 'Restore this version')}
+            </Button>
+          </SheetFooter>
+        ) : null}
+        <AlertDialog open={!!confirming} onOpenChange={(open) => !open && setConfirming(undefined)}>
+          <AlertDialogContent>
+            <AlertDialogHeader>
+              <AlertDialogTitle>{t('version.confirmVersionRestoration', 'Confirm version restoration')}</AlertDialogTitle>
+              <AlertDialogDescription>
+                {(t('version.aboutToRestore', 'You are about to restore this {label} to the state it was in on {versionDate}.') ?? '')
+                  .replace('{label}', titleOf({ kayan, copy }))
+                  .replace('{versionDate}', when(version.updatedAt))}
+              </AlertDialogDescription>
+            </AlertDialogHeader>
+            <AlertDialogFooter className="max-sm:[&_button]:h-11">
+              <AlertDialogCancel>{t('admin.cancel', 'Cancel')}</AlertDialogCancel>
+              <AlertDialogAction data-button="confirm-restore" disabled={restoring} onClick={() => confirming && void restore(confirming.draft)}>
+                {confirming?.draft ? t('version.restoreAsDraft', 'Restore as draft') : t('version.restore', 'Restore')}
+              </AlertDialogAction>
+            </AlertDialogFooter>
+          </AlertDialogContent>
+        </AlertDialog>
+        {/* The registry's close, named in the page's language, in place of the
+            primitive's English one. */}
+        <CloseButton Close={SheetClose} label={t('admin.close', 'Close') ?? 'Close'} />
+      </SheetContent>
+    </Sheet>
+  )
+}

package/template/templates/asas/src/ui-portal/courses-home.tsx

@@ -0,0 +1,96 @@
+// What `/portal` itself draws for the courses example, in the portal's own look: a greeting, the viewer's next
+// session, and a few courses on offer it holds no seat in yet. It is the asas's own, since a screen's root page is
+// drawn from the project, and draws with the courses feature's portal pieces.
+import { useSyncExternalStore } from 'react'
+import { CalendarDays, MapPin } from 'lucide-react'
+import { useQuery } from '@tanstack/react-query'
+import { useClient, useLocale, useScreen, useUser } from 'mithaq/admin/react'
+import { buttonVariants } from '@/components/ui/button'
+import { Skeleton } from '@/components/ui/skeleton'
+import { PortalShell, display } from '@asas/courses/portal/ui/shell.tsx'
+import { CardsLoading, Cover, CourseCard, ReadFailed, usePlace } from '@asas/courses/portal/ui/parts.tsx'
+import { byWhen, partOfDay, startsIn, whenOf } from '@asas/courses/portal/ui/rules.ts'
+import { catalogueOf, readSeats } from '@asas/courses/portal/ui/reads.ts'
+
+/** How many courses the home offers before its link to the rest. */
+const offered = 3
+
+/** The hour on the viewer's own clock, and none on the server, which knows neither the clock nor the zone. */
+const useHour = () => useSyncExternalStore(() => () => {}, () => new Date().getHours(), () => undefined)
+
+export function Home() {
+  const { locale, t } = useLocale()
+  const client = useClient()
+  const screen = useScreen()
+  const user = useUser()
+  const place = usePlace()
+  const hour = useHour()
+  const now = Date.now()
+  // The viewer's own seats, whoever it is: an instructor reads every seat, and its next session is still its own.
+  const mine = useQuery({
+    queryKey: ['portal-mine', user.id],
+    queryFn: () => readSeats({ client, maxLimit: screen.maxLimit, where: { student: { equals: user.id } } }),
+    enabled: !!user.id,
+  })
+  const catalogue = useQuery({ queryKey: ['portal-catalogue'], queryFn: () => catalogueOf({ client, maxLimit: screen.maxLimit, now }), staleTime: 30_000 })
+  const next = mine.data && byWhen(mine.data, now).upcoming[0]
+  const held = new Set(mine.data?.map((one) => String(one.course?.id)))
+  // A course the student may enroll itself in, with a session to come, and no seat of its own in it yet.
+  const open = catalogue.data?.courses.filter((course) => course.selfEnroll === true && !held.has(String(course.id)) && catalogue.data.next.has(String(course.id))).slice(0, offered)
+  // One sentence per locale, so each says the name where its grammar puts it.
+  const greeting = (hour === undefined ? t('portal.welcome', 'Welcome, {name}') : t(`portal.greeting.${partOfDay(hour)}`, 'Hello, {name}'))!.replace('{name}', () => user.name)
+  return (
+    <PortalShell
+      regions={{
+        header: <h1 className={`${display} text-3xl leading-tight sm:text-4xl`}>{greeting}</h1>,
+        main: (
+          <div data-dashboard="portal" className="grid gap-8">
+            {mine.isPending && user.id ? <Skeleton className="h-52 rounded-3xl" /> : next ? (
+              <section aria-labelledby="next" className="bg-primary text-primary-foreground grid overflow-hidden rounded-3xl md:grid-cols-[3fr_2fr]">
+                <div className="grid content-start gap-3.5 p-5 sm:p-8">
+                  <h2 id="next" className="text-sm opacity-85">{t('portal.yourNext', 'Your next session')}</h2>
+                  <p className={`${display} text-2xl leading-tight sm:text-3xl`}>{String(next.course?.title ?? '')}</p>
+                  <div className="grid gap-1.5 text-[15px]">
+                    <span className="flex items-center gap-2"><CalendarDays aria-hidden className="size-4.5 shrink-0" />{whenOf({ value: next.startsAt, locale })}</span>
+                    {place(next.session) ? <span className="flex items-center gap-2"><MapPin aria-hidden className="size-4.5 shrink-0" />{place(next.session)}</span> : null}
+                  </div>
+                  <div className="flex flex-wrap items-center justify-between gap-3 pt-1">
+                    <span className="text-sm opacity-85">{t('portal.startsIn', 'Starts {when}')!.replace('{when}', () => startsIn({ value: next.startsAt, now, locale }) ?? '')}</span>
+                    {next.course ? (
+                      <a href={`${screen.path}/courses/${encodeURIComponent(String(next.course.id))}`} className={buttonVariants({ variant: 'secondary', className: 'bg-card text-primary h-11 rounded-full px-5 font-semibold' })}>
+                        {t('portal.viewCourse', 'View course')}
+                      </a>
+                    ) : null}
+                  </div>
+                </div>
+                <Cover course={next.course} cover={next.cover} className="hidden h-full min-h-60 w-full md:block" />
+              </section>
+            ) : null}
+            <section aria-labelledby="join" className="grid gap-4">
+              <div className="flex items-baseline justify-between gap-3">
+                <h2 id="join" className={`${display} text-xl sm:text-2xl`}>{t('portal.canJoin', 'Courses you can join')}</h2>
+                <a href={`${screen.path}/courses`} className="text-primary text-[15px] font-medium underline-offset-4 hover:underline">{t('portal.seeAll', 'See all courses')}</a>
+              </div>
+              {catalogue.isError ? <ReadFailed retry={() => void catalogue.refetch()} /> : !open ? <CardsLoading /> : open.length ? (
+                <div className="grid grid-cols-[repeat(auto-fill,minmax(16rem,1fr))] gap-5">
+                  {open.map((course) => (
+                    <CourseCard
+                      key={String(course.id)}
+                      course={course}
+                      cover={catalogue.data!.covers.get(String(course.cover))}
+                      next={catalogue.data!.next.get(String(course.id))}
+                      tags={catalogue.data!.tags}
+                      href={`${screen.path}/courses/${encodeURIComponent(String(course.id))}`}
+                    />
+                  ))}
+                </div>
+              ) : (
+                <p className="text-muted-foreground text-sm">{t('portal.noneToJoin', 'No course has a session coming up just now.')}</p>
+              )}
+            </section>
+          </div>
+        ),
+      }}
+    />
+  )
+}

package/template/templates/asas/src/ui-portal/home.tsx

@@ -0,0 +1,73 @@
+// What `/portal` itself draws in a project without the courses example, whose
+// portal draws its own home: a greeting, then the dashboard home's figure card
+// for each list below, with how many rows of it the viewer may read and a link
+// to it. A list the nav does not offer the viewer has no card, and a list whose
+// count the viewer may not read, or whose count failed, shows a dash in place
+// of the figure.
+import type { ReactNode } from 'react'
+import type { LoaderTools, PageProps } from 'mithaq/admin'
+import { useLocale, useScreen, useUser } from 'mithaq/admin/react'
+import { KpiCard } from '@asas/mithaq/ui/kpi-card.tsx'
+import { ScreenNav, navLabel } from '@asas/mithaq/ui/screen-nav.tsx'
+import { PortalTopShell } from '@asas/mithaq/ui/top-shell.tsx'
+
+/** The lists the home counts, each with its card's icon and the rows its list is held to. */
+// A list of the project's own goes here, as `['tags', <Tags className="size-4" />]`.
+const figures: readonly [kayan: string, icon: ReactNode, where?: object][] = []
+
+/**
+ * How many rows of each list the viewer may count, read as the viewer, keyed
+ * by its kayan. A kayan that keeps drafts is counted as its list reads it, the
+ * latest draft of every row for a reader of `findVersions`, with `find` and a
+ * page of one row, since `count` reads only the published ones.
+ */
+export const loader = async ({ client, access }: LoaderTools): Promise<Record<string, number | undefined>> =>
+  Object.fromEntries(
+    await Promise.all(
+      figures.map(async ([kayan, , where]) => {
+        const operations = access.collections?.[kayan]?.operations
+        if (operations?.count !== true) return [kayan, undefined] as const
+        const asked = operations.findVersions === true
+          ? client({ kayan, operation: 'find', input: { limit: 1, depth: 0, ...(where && { where }) }, draft: true })
+          : client({ kayan, operation: 'count', input: where ? { where } : {} })
+        return [kayan, await (asked as Promise<{ totalDocs: number }>).then((found) => found.totalDocs).catch(() => undefined)] as const
+      }),
+    ),
+  )
+
+export function Home({ loaderData: counts }: PageProps<Record<string, number | undefined>>) {
+  const { locale, t } = useLocale()
+  const user = useUser()
+  const screen = useScreen()
+  // One sentence per locale, so the Arabic greeting takes the Arabic comma.
+  const welcome = t('portal.welcome', 'Welcome, {name}')!.replace('{name}', () => user.name)
+  return (
+    <PortalTopShell
+      regions={{
+        header: <h1 title={welcome} className="truncate">{welcome}</h1>,
+        nav: <ScreenNav />,
+        main: (
+          <section data-dashboard="portal" className="@container grid gap-4">
+            <p className="text-muted-foreground">{t('portal.about', 'What you may open here, and how many of each you may read.')}</p>
+            <div className="grid grid-cols-1 gap-4 @md:grid-cols-2">
+              {figures.map(([kayan, icon]) => {
+                const entry = screen.nav.find((one) => one.kayan === kayan)
+                const counted = counts?.[kayan]
+                return entry ? (
+                  <KpiCard
+                    key={kayan}
+                    kpi={kayan}
+                    icon={icon}
+                    title={navLabel({ entry, screen, locale, t })}
+                    value={counted === undefined ? '—' : new Intl.NumberFormat(locale).format(counted)}
+                    footer={<a href={`${screen.path}${entry.path}`} className="text-foreground inline-flex items-center hover:underline max-sm:min-h-11">{t('portal.open', 'Open the list')}</a>}
+                  />
+                ) : null
+              })}
+            </div>
+          </section>
+        ),
+      }}
+    />
+  )
+}

package/template/templates/asas/src/ui-portal/page.tsx

@@ -0,0 +1,11 @@
+// The portal's one frame: a single column, `main`, drawn as a div because the
+// shell around it already holds the page's one main landmark. Its one track may
+// shrink below its widest child, so nothing wide stretches the portal past a phone.
+import type { ReactNode } from 'react'
+import type { LayoutProps } from 'mithaq/admin'
+
+export const regions = ['main'] as const
+
+export const Page = ({ regions, page }: LayoutProps<readonly ['main'], ReactNode>) => (
+  <div data-layout="page" data-page={page.path} className="grid grid-cols-[minmax(0,1fr)] gap-4">{regions.main}</div>
+)