create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/features/roles/roles/ui/role-form.tsx

@@ -0,0 +1,267 @@
+// Draws a custom role's slug, its label in every locale and its keys as badges
+// in place of the form's leaves. The form still holds, checks and saves the
+// values; this reads and writes them through `useForm()`, and reads each box's
+// refusal through `useKayanField`, so a box says it is required, says what is
+// wrong under itself once left or refused, and marks itself invalid.
+import type { ComponentProps as ElementProps, ReactNode } from 'react'
+import { ChevronDown } from 'lucide-react'
+import type { ComponentProps } from 'mithaq/admin'
+import { useAccess, useForm, useKayan, useLocale, useScreen } from 'mithaq/admin/react'
+import { Badge } from '@/components/ui/badge'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible'
+import { Input } from '@/components/ui/input'
+import { ariaRequired } from 'mithaq-admin/control-props.ts'
+import { FieldShell, describedBy } from 'mithaq-admin/field-shell.tsx'
+import { useKayanField } from 'mithaq-admin/form-context.tsx'
+import { grantable } from '@asas/mithaq/roles/grants.ts'
+import { projectStatements } from '@asas/mithaq/roles/statements.ts'
+
+/** The key a tenant's role may never hold, which the role kayan refuses by name, so no badge offers it. */
+const BACKOFFICE_KEY = 'screen.backoffice'
+
+type Key = { key: string; label: string }
+type Group = { name: string; label: string; operations: Key[]; fields: Key[] }
+
+/**
+ * The keys a badge may offer, grouped: the screens the viewer enters, then each
+ * kayan of this screen, its operations and then its fields, each named in the
+ * viewer's locale. The screen's own projection is the catalog here, and the
+ * server checks each key against `asas.catalog` and the granter anyway.
+ */
+const useGroups = (): Group[] => {
+  const screen = useScreen()
+  const access = useAccess()
+  const { locale, t } = useLocale()
+  const screens = (access.screens ?? []).map((name) => `screen.${name}`).filter((key) => key !== BACKOFFICE_KEY)
+  return [
+    {
+      name: 'screen',
+      label: t('dashboard.permissionsScreens', 'Screens') ?? 'Screens',
+      operations: screens.map((key) => ({ key, label: t(`screens.${key.slice('screen.'.length)}`) ?? key })),
+      fields: [],
+    },
+    ...Object.values(screen.kayan).map((kayan) => ({
+      name: kayan.name,
+      label: t(`${kayan.name}.plural`) ?? kayan.name,
+      operations: [...kayan.operations.map((one) => one.name), ...(Object.hasOwn(projectStatements, kayan.name) ? projectStatements[kayan.name as keyof typeof projectStatements] : [])].map((name) => ({
+        key: `${kayan.name}.${name}`,
+        label: t(`${kayan.name}.operations.${name}`) ?? t(`permissions.${name}`) ?? name,
+      })),
+      // A generated auth kayan's fields carry no label of their own, and the
+      // project's copy names them.
+      fields: kayan.fields.map((field) => ({ key: `${kayan.name}.fields.${field.name}`, label: field.label?.[locale] ?? t(`${kayan.name}.${field.name}`) ?? field.name })),
+    })),
+  ]
+}
+
+/**
+ * A role's or a group's keys behind a row that names them and counts what they grant, closed at
+ * first so a page of roles reads as a list of names; `defaultOpen` where the keys are the page's
+ * work. A closed panel is `hidden="until-found"` once the page runs, so it is in the first paint
+ * and a find on the page opens it. `named` names a row that draws no label of its own, so a reader
+ * of the screen hears whose keys it opens. Every permission has nothing to open, so it is said.
+ */
+export function Grants({ label, named, held, heading, defaultOpen, children, ...root }: { label?: ReactNode; named?: string; held: readonly string[]; heading?: boolean; defaultOpen?: boolean; children: ReactNode } & ElementProps<'div'>) {
+  const { locale, t } = useLocale()
+  const count = held.length === 1
+    ? t('dashboard.permissionsCountOne', '1 permission')
+    : (t('dashboard.permissionsCount', '{count} permissions') ?? '{count} permissions').replace('{count}', () => new Intl.NumberFormat(locale).format(held.length))
+  if (held.includes('*')) {
+    return (
+      <div {...root} className="flex items-center gap-2">
+        {/* Where a chevron stands on every other row, so the names line up. */}
+        <span aria-hidden="true" className="size-4 shrink-0" />
+        {label}
+        <span className="text-muted-foreground text-xs">{t('dashboard.everyPermission', 'Every permission')}</span>
+      </div>
+    )
+  }
+  const trigger = (
+    <CollapsibleTrigger aria-label={named && `${named}: ${count}`} className="group flex w-full cursor-pointer items-center gap-2 text-start max-sm:min-h-11">
+      <ChevronDown aria-hidden="true" className="text-muted-foreground size-4 shrink-0 transition-transform group-data-[panel-open]:rotate-180" />
+      {label}
+      <span className="text-muted-foreground text-xs font-normal">{count}</span>
+    </CollapsibleTrigger>
+  )
+  return (
+    <Collapsible {...root} defaultOpen={defaultOpen}>
+      {heading ? <h3 className="text-sm font-medium">{trigger}</h3> : trigger}
+      <CollapsibleContent hiddenUntilFound className="ps-6 pt-2">{children}</CollapsibleContent>
+    </Collapsible>
+  )
+}
+
+/**
+ * The keys a role holds as badges, grouped by screen and kayan, each group behind its count: closed where they are
+ * read, open in the editor, whose work they are. With `onChange`
+ * each badge is a toggle, a key the viewer may not hand over disabled; without it
+ * only the keys held are drawn. A key no group names stays, under "Other", so a
+ * save never drops one.
+ */
+export function PermissionBadges({ held, onChange, busy }: { held: readonly string[]; onChange?: (keys: string[]) => void; busy?: boolean }) {
+  const access = useAccess()
+  const { t } = useLocale()
+  // Read only, every screen the role enters is named, whichever the viewer
+  // enters: the backoffice reads a tenant's role, which holds `screen.dashboard`.
+  const groups = useGroups().map((group) =>
+    group.name === 'screen' && !onChange
+      ? { ...group, operations: held.filter((key) => key.startsWith('screen.')).map((key) => ({ key, label: t(`screens.${key.slice('screen.'.length)}`) ?? key })) }
+      : group,
+  )
+  const named = new Set(groups.flatMap((group) => [...group.operations, ...group.fields].map((one) => one.key)))
+  const other = held.filter((key) => !named.has(key))
+  /**
+   * A key no group names, which is a kayan this screen does not draw or a
+   * column the viewer may not read, still by its words where the copy has
+   * them, `<kayan>.<field>` or the operation's, and by the key only where it
+   * has none.
+   */
+  const otherLabel = (key: string) => {
+    const [kayan, second, field] = key.split('.')
+    return (second === 'fields' && field ? t(`${kayan}.${field}`) : second ? (t(`${kayan}.operations.${second}`) ?? t(`permissions.${second}`)) : undefined) ?? key
+  }
+  const toggle = (key: string) => onChange?.(held.includes(key) ? held.filter((one) => one !== key) : [...held, key])
+  const badges = (keys: Key[]) => {
+    const shown = onChange ? keys : keys.filter((one) => held.includes(one.key))
+    return shown.length ? (
+      // On a phone each chip is a 44 pixel target, with room between them, so
+      // a thumb does not take the key beside the one it meant.
+      <div className="flex flex-wrap gap-1.5 max-sm:gap-2">
+        {shown.map(({ key, label }) => {
+          const on = held.includes(key)
+          if (!onChange) return <Badge key={key} variant="outline" data-key={key}>{label}</Badge>
+          const disabled = busy === true || !grantable(access, [key])
+          return (
+            <Badge
+              key={key}
+              variant={on ? 'default' : 'outline'}
+              data-key={key}
+              data-selected={on}
+              data-disabled={disabled}
+              className="cursor-pointer data-[disabled=true]:cursor-not-allowed data-[disabled=true]:opacity-50 max-sm:h-11 max-sm:min-w-11 max-sm:px-3"
+              render={<button type="button" aria-pressed={on} disabled={disabled} onClick={() => toggle(key)} />}
+            >
+              {label}
+            </Badge>
+          )
+        })}
+      </div>
+    ) : null
+  }
+  if (held.includes('*')) return <Badge variant="outline">{t('dashboard.everyPermission', 'Every permission')}</Badge>
+  return (
+    <div data-permissions="" className="grid gap-2">
+      {groups.map((group) => {
+        const operations = badges(group.operations)
+        const fields = badges(group.fields)
+        const keys = [...group.operations, ...group.fields].map((one) => one.key)
+        return operations || fields ? (
+          <Grants key={group.name} data-group={group.name} heading defaultOpen={Boolean(onChange)} label={<span>{group.label}</span>} held={held.filter((key) => keys.includes(key))}>
+            <div className="grid gap-1.5">
+              {operations}
+              {fields ? (
+                <>
+                  <p className="text-muted-foreground text-xs">{t('dashboard.permissionsFields', 'Fields')}</p>
+                  {fields}
+                </>
+              ) : null}
+            </div>
+          </Grants>
+        ) : null
+      })}
+      {other.length ? (
+        <Grants data-group="" heading defaultOpen={Boolean(onChange)} label={<span>{t('dashboard.permissionsOther', 'Other')}</span>} held={other}>
+          {badges(other.map((key) => ({ key, label: otherLabel(key) })))}
+        </Grants>
+      ) : null}
+    </div>
+  )
+}
+
+export function RoleForm(_: ComponentProps) {
+  const { disabled: readOnly, getData, setValue } = useForm()
+  const { t } = useLocale()
+  const fields = useKayan().fields
+  const labelField = fields.find((field) => field.name === 'label')
+  const values = getData()
+  const label = (values.label ?? {}) as Record<string, string>
+  const permissions = Array.isArray(values.permissions) ? (values.permissions as string[]) : []
+  const named = { name: useKayanField('name'), label: useKayanField('label'), permissions: useKayanField('permissions') }
+  const required = (name: string) => ariaRequired(fields.find((field) => field.name === name) ?? { rules: {} })
+  /** Whether one locale's label box is the one refused: those the refusal names, or every one where it names none. */
+  const labelWrong = (locale: string) => (named.label.error && (named.label.locales?.includes(locale) ?? true) ? named.label.error : undefined)
+  const nameDescription = t('roles.name.description', 'The role\'s slug, which every assignment of it names, such as course-editor. People read the role by its label below.')
+  // Two cards, as a page's sections are drawn, so a role's page reads as the
+  // course pages do: the role's names, then its keys.
+  const section = (heading: string, body: ReactNode) => (
+    <Card className="rounded-lg">
+      <CardHeader>
+        <CardTitle>
+          <h2 className="text-base font-medium">{heading}</h2>
+        </CardTitle>
+      </CardHeader>
+      <CardContent className="grid gap-4">{body}</CardContent>
+    </Card>
+  )
+  return (
+    <div data-role-form="" className="grid gap-4">
+      {section(t('roles.singular', 'Role') ?? 'Role', (
+        <>
+          {/* The name is a slug, so the box says so and reads left to right. */}
+          <FieldShell id="roles-name" label={t('roles.name', 'Name') ?? 'Name'} description={nameDescription} error={named.name.error} onBlur={named.name.onBlur}>
+            <Input
+              id="roles-name"
+              dir="ltr"
+              aria-describedby={describedBy({ id: 'roles-name', description: nameDescription, error: named.name.error })}
+              aria-invalid={named.name.error ? true : undefined}
+              aria-required={required('name')}
+              value={String(values.name ?? '')}
+              readOnly={readOnly}
+              onChange={(event) => setValue('name', event.target.value)}
+            />
+          </FieldShell>
+          {Object.keys(labelField?.label ?? {}).map((locale) => {
+            const id = `roles-label-${locale}`
+            const error = labelWrong(locale)
+            return (
+              <FieldShell key={locale} id={id} label={`${t('roles.label', 'Label')} (${t(`locale.${locale}`) ?? locale})`} error={error} onBlur={named.label.onBlur}>
+                <Input
+                  id={id}
+                  lang={locale}
+                  dir="auto"
+                  aria-describedby={describedBy({ id, error })}
+                  aria-invalid={error ? true : undefined}
+                  aria-required={required('label')}
+                  value={label[locale] ?? ''}
+                  readOnly={readOnly}
+                  onChange={(event) => setValue('label', { ...label, [locale]: event.target.value })}
+                />
+              </FieldShell>
+            )
+          })}
+        </>
+      ))}
+      {section(t('roles.permissions', 'Permissions') ?? 'Permissions', (
+        <>
+          {/* One group for the badges, named by its section and pointing at its
+              refusal, so it marks itself as a box does. A group takes no
+              `aria-required`, so its name says it is required instead. */}
+          <div
+            role="group"
+            aria-label={t('dashboard.permissionsRequired', 'Permissions, required')}
+            aria-invalid={named.permissions.error ? true : undefined}
+            aria-describedby={named.permissions.error ? 'roles-permissions-error' : undefined}
+          >
+            <PermissionBadges held={permissions} busy={readOnly} onChange={(keys) => setValue('permissions', keys)} />
+          </div>
+          {named.permissions.error ? (
+            <p id="roles-permissions-error" role="alert" className="text-destructive text-sm">
+              {named.permissions.error}
+            </p>
+          ) : null}
+        </>
+      ))}
+    </div>
+  )
+}

package/template/templates/features/roles/roles/ui/roles.tsx

@@ -0,0 +1,190 @@
+// A fixed role is one this project ships, whose keys are code and never a row, so nothing here
+// writes one.
+import { useState } from 'react'
+import { Lock } from 'lucide-react'
+import type { ButtonProps, CellProps, Row } from 'mithaq/admin'
+import { useClient, useList, useLocale, useRecord, useScreen } from 'mithaq/admin/react'
+import { tenantRoles } from '@asas/mithaq/roles/tenant-roles.ts'
+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 { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table'
+import { Grants, PermissionBadges } from './role-form.tsx'
+
+/** A role's label in the viewer's locale, and its slug only where a row carries none. */
+export const labelOf = (row: Row | null | undefined, locale: string) => {
+  const label = row?.label as Record<string, string> | null | undefined
+  return label?.[locale] ?? String(row?.name ?? '')
+}
+
+/**
+ * The list node's component: the fixed roles first, from their code, each with a lock, then the
+ * organization's own. Each row names a role and counts what it grants, and opens to its keys and,
+ * for a custom role, a link to its page. It draws no row menu; a custom role's delete is its page's.
+ */
+export function RolesTable() {
+  const { page, creates, href, newHref } = useList()
+  const { locale, t } = useLocale()
+  return (
+    <div data-roles="" className="grid gap-4">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <p className="text-muted-foreground">{t('dashboard.rolesAbout', 'Fixed roles ship with the project and cannot be changed here. Custom roles are this organization\'s own.')}</p>
+        {creates ? (
+          <Button size="sm" className="max-sm:h-11" nativeButton={false} render={<a href={newHref} />}>
+            {t('dashboard.rolesNew', 'New role')}
+          </Button>
+        ) : null}
+      </div>
+      <div className="overflow-hidden rounded-lg border">
+        <Table>
+          <TableHeader className="bg-muted/50">
+            <TableRow>
+              <TableHead scope="col">{t('roles.name', 'Name')}</TableHead>
+              <TableHead scope="col">{t('dashboard.rolesKind', 'Kind')}</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {Object.entries(tenantRoles).map(([name, role]) => (
+              <TableRow key={name} data-row={name} data-fixed="true">
+                <TableCell className="whitespace-normal">
+                  <Grants
+                    data-fixed-role=""
+                    label={
+                      <span className="flex items-center gap-1.5 font-medium">
+                        <Lock data-lock="" className="text-muted-foreground size-3.5" aria-hidden="true" />
+                        <span>{(role.label as Readonly<Record<string, string>>)[locale] ?? name}</span>
+                      </span>
+                    }
+                    held={role.permissions === '*' ? ['*'] : role.permissions}
+                  >
+                    <div className="grid gap-2">
+                      <p className="text-muted-foreground text-sm">{t('dashboard.rolesFixedAbout', 'This role ships with the project. What it holds is code, so it cannot be edited or deleted here.')}</p>
+                      <PermissionBadges held={role.permissions === '*' ? ['*'] : role.permissions} />
+                    </div>
+                  </Grants>
+                </TableCell>
+                <TableCell className="align-top">
+                  <Badge variant="secondary">{t('dashboard.rolesFixed', 'Fixed')}</Badge>
+                </TableCell>
+              </TableRow>
+            ))}
+            {page.docs.map((row) => {
+              const id = String(row.id)
+              const label = labelOf(row, locale)
+              const open = (
+                <a href={href(id)} className="text-primary justify-self-start text-sm underline underline-offset-4 max-sm:inline-flex max-sm:min-h-11 max-sm:items-center">
+                  {(t('dashboard.rolesOpen', 'Open {role}') ?? 'Open {role}').replace('{role}', () => label)}
+                </a>
+              )
+              return (
+                <TableRow key={id} data-row={id} data-fixed="false">
+                  <TableCell className="whitespace-normal">
+                    {/* A role whose keys the viewer may not read comes without them, so it is named and linked and counts nothing. */}
+                    {Array.isArray(row.permissions) ? (
+                      <Grants label={<span className="font-medium">{label}</span>} held={row.permissions as string[]}>
+                        <div className="grid gap-2">
+                          {open}
+                          <PermissionBadges held={row.permissions as string[]} />
+                        </div>
+                      </Grants>
+                    ) : (
+                      <div className="grid gap-1">
+                        <span className="font-medium">{label}</span>
+                        {open}
+                      </div>
+                    )}
+                  </TableCell>
+                  <TableCell className="align-top">
+                    <Badge variant="outline">{t('dashboard.rolesCustom', 'Custom')}</Badge>
+                  </TableCell>
+                </TableRow>
+              )
+            })}
+          </TableBody>
+        </Table>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * A role's keys where a page reads them as a value: grouped and named as a fixed role's page draws
+ * them, never a run of slugs.
+ */
+export function Permissions({ value }: Pick<CellProps, 'value'>) {
+  return <PermissionBadges held={Array.isArray(value) ? (value as string[]) : []} />
+}
+
+/** A page of rows as the client answers it, read untyped since a feature never imports the asas it is built into. */
+type Found = { docs?: Record<string, unknown>[] } | undefined
+
+/**
+ * A custom role's delete, the danger zone's button. A role any member holds is not deleted, so the
+ * button reads who holds it first: while anyone does, the dialog names them, each linking to their
+ * roles on the Members page, and offers no delete. A holder list the viewer may not read asks as any
+ * delete does, and the server refuses it there.
+ */
+export function DeleteRole({ run, busy }: ButtonProps) {
+  const record = useRecord()
+  const client = useClient()
+  // Read at the build's most rows one served read answers, since a page past
+  // it is a 400 the catch below would read as no holders at all.
+  const { path, maxLimit } = useScreen()
+  const { t } = useLocale()
+  const [open, setOpen] = useState(false)
+  const [holders, setHolders] = useState<{ id: string; name: string }[]>([])
+  const ask = async () => {
+    const held = await client({ kayan: 'memberRoles', operation: 'find', input: { where: { role: { equals: record?.name as string } }, limit: maxLimit, depth: 0 } }).catch(() => undefined) as Found
+    const ids = held?.docs?.map((row) => String(row.user)) ?? []
+    const named = ids.length ? await client({ kayan: 'user', operation: 'find', input: { where: { id: { in: ids } }, limit: maxLimit, depth: 0 } }).catch(() => undefined) as Found : undefined
+    // A holder whose name the viewer may not read is "a member", never a raw id, and the link still
+    // opens their roles.
+    setHolders(ids.map((id) => ({ id, name: (named?.docs?.find((one) => one.id === id)?.name as string | undefined) ?? t('dashboard.rolesHolderUnnamed', 'A member') ?? '' })))
+    setOpen(true)
+  }
+  return (
+    <AlertDialog open={open} onOpenChange={setOpen}>
+      <Button type="button" variant="destructive" data-button="delete" disabled={busy} onClick={() => void ask()}>
+        {t('admin.delete', 'Delete')}
+      </Button>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{holders.length ? t('dashboard.rolesHeldTitle', 'Members hold this role') : t('dashboard.rolesDeleteTitle', 'Delete this role?')}</AlertDialogTitle>
+          <AlertDialogDescription data-held={holders.length}>
+            {holders.length
+              ? t('dashboard.rolesHeld', 'A role a member holds is not deleted. Take it from each of them on the Members page first.')
+              : t('admin.deleteWarning', 'This cannot be undone.')}
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        {holders.length ? (
+          <ul data-holders="" className="grid gap-1 text-sm">
+            {holders.map((one) => (
+              <li key={one.id}>
+                <a href={`${path}/members?member=${encodeURIComponent(one.id)}`} className="underline underline-offset-4">
+                  {one.name}
+                </a>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+        <AlertDialogFooter>
+          <AlertDialogCancel>{t('admin.cancel', 'Cancel')}</AlertDialogCancel>
+          {holders.length ? null : (
+            <AlertDialogAction variant="destructive" disabled={busy} onClick={() => void run({})}>
+              {t('roles.delete.confirm', 'Delete for good')}
+            </AlertDialogAction>
+          )}
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}

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

@@ -0,0 +1,3 @@
+import { settings } from './settings/settings.ts'
+
+export const global = [settings] as const

package/template/templates/features/settings/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@asas/settings",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "dependencies": {
+    "@asas/mithaq": "*",
+    "mithaq": "*"
+  }
+}

package/template/templates/features/settings/settings/settings.ts

@@ -0,0 +1,64 @@
+import { defaultFields, defaultGlobalFields, defaultGlobalOperations } from 'mithaq'
+import { defineGlobal, organization, rows } from '@asas/mithaq'
+import { backofficeClosed, tenantAccess } from '@asas/mithaq/roles/tenant-access.ts'
+import { appPage } from '@asas/mithaq/mithaq/pages.ts'
+
+/**
+ * The project's settings, one row per tenant, because this global places
+ * `organization`. `asas.global.settings.operations.findOne({}, { actor })`
+ * answers the active organization's row or null, and
+ * `asas.global.settings.operations.update(data, { actor })` writes it, making it
+ * on the first call.
+ *
+ * One row per tenant is two lines here, because nothing rewrites a global's
+ * fields: the organization is unique, since it is the column that keeps the row
+ * single, and `globalType` is not unique, since every tenant's row carries the
+ * same name. `buildAsas` refuses either written the other way.
+ */
+export const settings = defineGlobal({
+  name: 'settings',
+  fields: {
+    ...defaultFields,
+    organization: { ...organization, rules: { ...organization.rules, unique: true } },
+    // The site has no name of its own: it is the organization's, in every locale.
+    maintenance: {
+      kind: 'checkbox',
+      label: { en: 'Maintenance', ar: 'الصيانة' },
+      description: {
+        en: 'While this is on, the portal tells students it is closed for maintenance. Staff keep working.',
+        ar: 'ما دام هذا مفعلا، تخبر البوابة الطلاب بأنها مغلقة للصيانة. ويواصل الموظفون عملهم.',
+      },
+    },
+    // Where a student writes to, the one address the portal shows: at its foot, and on its maintenance page.
+    contactEmail: { kind: 'email', label: { en: 'Contact email', ar: 'بريد التواصل' } },
+    // The column default is the one the table was made with, so the committed
+    // migrations still describe it.
+    globalType: { ...defaultGlobalFields.globalType, rules: { required: true, defaultValue: 'settings' } },
+  },
+  // Its own rows: the language's, and every backoffice role closed. The backoffice
+  // lists no global, since a list across tenants reads by `find` and a global
+  // declares none, so it reads none, 403 `error.forbidden.read`. A global takes
+  // read and update alone, and the other two the rows compile are never reached.
+  access: rows({ ...tenantAccess, ...backofficeClosed }) as Pick<ReturnType<typeof rows>, 'read' | 'update'>,
+  targets: {
+    service: { operations: defaultGlobalOperations },
+    // A global is one row, so its page is a custom one with no id: its form
+    // updates the row there is. Its fields in sections under its sentence, and the
+    // yes or no setting a switch with its label beside it.
+    dashboard: {
+      description: {
+        en: 'Where students reach the school, and whether the portal is open to them.',
+        ar: 'أين يتواصل الطلاب مع المدرسة، وهل البوابة مفتوحة لهم.',
+      },
+      pages: {
+        settings: {
+          path: '/settings',
+          page: appPage([{ layout: 'record', main: [{ form: [
+            { section: 'contact', label: { en: 'Contact', ar: 'التواصل' }, fields: ['contactEmail'] },
+            { section: 'availability', label: { en: 'Availability', ar: 'الإتاحة' }, fields: [{ field: 'maintenance', component: 'switch' }] },
+          ] }] }]),
+        },
+      },
+    },
+  },
+})

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

@@ -0,0 +1,3 @@
+import { tags } from './tags/tags.ts'
+
+export const kayan = [tags] as const

package/template/templates/features/tags/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@asas/tags",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "dependencies": {
+    "@asas/mithaq": "*",
+    "mithaq": "*",
+    "zod": "^4.6.5"
+  }
+}

package/template/templates/features/tags/tags/tags.ts

@@ -0,0 +1,80 @@
+import { defaultFields } from 'mithaq'
+import { z } from 'zod'
+import { defineKayan, organization } from '@asas/mithaq'
+import { appPage, danger, backofficeList, backofficeRecord } from '@asas/mithaq/mithaq/pages.ts'
+import { expectedUpdatedAt } from '@asas/mithaq/steps/expected-updated-at.ts'
+
+const tag = [{ section: 'tag', label: { en: 'Tag', ar: 'الوسم' }, fields: ['name'] }] as const
+
+/**
+ * A label a course may carry any number of, and which any number of courses may
+ * carry: the other end of `courses.tags`, the one many-to-many this template
+ * declares. It places `organization`, so a tag is its organization's own and
+ * the runner refuses a course pointing at another tenant's tag.
+ */
+export const tags = defineKayan({
+  name: 'tags',
+  messages: {
+    singular: { en: 'Tag', ar: 'وسم' },
+    plural: { en: 'Tags', ar: 'الوسوم' },
+  },
+  // What the picker on `courses.tags` shows for each row, and what its search
+  // runs a `like` over. Without it every tag is a uuid.
+  targets: {
+    // Every organization's rows on the backoffice, read-only, and each row's
+    // record, which only reads.
+    backoffice: {
+      useAsTitle: 'name',
+      pages: {
+        ...backofficeList('/tags', { columns: ['name', 'organization', 'createdAt'], filters: ['organization'], search: ['name'] }),
+        ...backofficeRecord({ path: '/tags/:id', main: [{ section: 'tag', label: { en: 'Tag', ar: 'الوسم' }, fields: ['name'] }] }),
+      },
+    },
+    // A create opens as a sheet over the list. The name is copy a screen shows
+    // as a label, so it is one string per locale, and every screen reads it in
+    // the viewer's.
+    dashboard: {
+      useAsTitle: 'name',
+      description: {
+        en: 'Labels the organization groups its records by.',
+        ar: 'تسميات تجمع بها المؤسسة سجلاتها.',
+      },
+      pages: {
+        list: { path: '/tags', page: appPage([{ layout: 'table', main: [{ list: { columns: ['name', 'createdAt'], search: ['name'] } }] }]) },
+        // The drawer's title says it makes a tag, so its one box is drawn
+        // bare rather than under a second heading that says "Tag" again.
+        create: { path: '/tags/new', mode: 'drawer', page: appPage([{ layout: 'record', main: [{ form: ['name'] }] }]) },
+        edit: { path: '/tags/:id', page: appPage([{ layout: 'record', main: [{ form: tag }], danger: danger() }]) },
+      },
+    },
+    service: {
+      operations: ({ defaults }) => ({
+        ...defaults,
+        /**
+         * The shipped update list with the `expectedUpdatedAt` step before it and
+         * its input widened by the key the step reads. A caller who sends the
+         * instant it read the tag at is refused 409 when the tag has changed
+         * since. The dashboard's edit form sends it, because the screen host
+         * reads that this input takes the key, so a second tab's stale save is
+         * the 409. The key stays optional, so a caller that sends none, a bulk
+         * update among them, saves as before.
+         */
+        update: {
+          input: ({ update }) => update.extend({ expectedUpdatedAt: z.date().optional() }),
+          steps: ({ steps }) => [expectedUpdatedAt, steps.update],
+        },
+      }),
+    },
+  },
+  fields: {
+    ...defaultFields,
+    organization,
+    name: {
+      kind: 'text',
+      label: { en: 'Name', ar: 'الاسم' },
+      // Each locale trimmed before it is judged, so a name of spaces is refused
+      // as required.
+      rules: { localized: true, required: true, trim: true, maxLength: 60, index: true },
+    },
+  },
+})