create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/mithaq/src/mithaq/auth/organizations.ts

@@ -0,0 +1,80 @@
+// How this project holds its people: how many organizations, and who may join. A module of its own,
+// importing nothing, so a page reads it without loading the provider. `create-mithaq` writes it; a
+// project changes it by hand, as the README's "Organization modes" says.
+
+/**
+ * How many organizations the project holds. In both modes a per-organization kayan places
+ * `organization` and core scopes it, so a switch moves no row.
+ *
+ * - `'many'`: each sign-up founds its own organization.
+ * - `'one'`: one organization, made on `/auth/first-run`.
+ *
+ * The tenant target reads it too: a start over more than one organization in `'one'` is refused.
+ */
+export const organizations: 'one' | 'many' = 'many'
+
+/**
+ * In `'one'`, whether a page names the organization. `false` says nothing of one: the first-run
+ * asks no name, the Members page is Users and the sidebar shows the app's name. `'many'` takes
+ * `true`: there a person switches between them by name.
+ */
+export const showOrganization: boolean = true
+
+/**
+ * In `'one'`, who may make an account. `'many'` takes `'open'` alone: there each
+ * sign-up founds its own organization.
+ *
+ * - `'invite'`: only someone holding an invitation, signing up with the invitation's id and address.
+ *   Every other sign-up is refused with one answer, which tells nobody whether an address has an
+ *   account.
+ * - `'open'`: anyone, who joins the organization as `joinRole` once their address is verified (or
+ *   at once when `verifyEmail` is false). A production start refuses it without a mailer.
+ */
+export const signUp: 'invite' | 'open' = 'open'
+
+/**
+ * The business role an open joiner is given, a slug of `roles/tenant-roles.ts`, or `null` for none:
+ * the person joins, reads nothing, and an administrator gives them a role on the Members page,
+ * which is how a project approves each joiner. Without the roles add-on it is `null`, and a joiner
+ * holds the provider's `member`. `'many'` takes `null`: nobody joins there but by invitation.
+ */
+export const joinRole: string | null = null
+
+/**
+ * Whether a new account proves its address by a mailed link before it signs in, read with an open
+ * sign-up: in `'one'`, before it joins too. `'many'` takes `true`: anyone founds an organization
+ * there, so a sign-up must tell nobody which addresses have an account.
+ */
+export const verifyEmail: boolean = true
+
+/**
+ * In `'one'` with an open sign-up and `verifyEmail`, the only address domains that may
+ * sign up, lowercase ASCII (`xn--` for an international one): `example.com` is that domain alone, and
+ * `*.example.com` every domain under it, never itself. Empty, any domain may.
+ */
+export const allowedDomains: readonly string[] = []
+
+/**
+ * The organization's name in each locale the language reads and no other, the first the one every other falls back to;
+ * the language refuses to load otherwise. In `'one'` it is the organization's name, which lives here, not on the row:
+ * start-up writes it onto the row, first-run asks none, and nobody renames it elsewhere. With `'many'` each organization
+ * names itself, and only its locales are read: the ones a founder's names are held to.
+ */
+export const organizationName: Readonly<Record<string, string>> = { en: 'My organization', ar: 'مؤسستي' }
+
+/** The locale an organization's `name` is in, which every other falls back to. */
+export const defaultLocale = Object.keys(organizationName)[0]!
+
+/**
+ * An organization's name in `locale`: `name` in the default locale, and elsewhere its `names` entry, the JSON the
+ * auth setup writes, where it holds one.
+ */
+export const nameIn = ({ name, names }: { name: string; names?: unknown }, locale: string): string => {
+  if (locale === defaultLocale || typeof names !== 'string') return name
+  try {
+    const own = (JSON.parse(names) as Record<string, unknown> | null)?.[locale]
+    return typeof own === 'string' && own ? own : name
+  } catch {
+    return name
+  }
+}

package/template/templates/mithaq/src/mithaq/pages.ts

@@ -0,0 +1,83 @@
+// The two page trees every kayan page of this project starts from, as plain
+// functions rather than anything a page inherits: a shell at the root, the
+// page's title in its header, the nav in its nav region where the shell has
+// one, and what the page passes in its main region. The side-column shell draws
+// its nav in the sidebar itself, so it has no nav region. A page that wants
+// another header or no nav writes its tree out instead.
+
+const holdsForm = (value: unknown): boolean =>
+  Array.isArray(value) ? value.some(holdsForm) : !!value && typeof value === 'object' && ('form' in value || Object.values(value).some(holdsForm))
+
+/**
+ * A page in the side-column shell the dashboard and the backoffice register as
+ * `app`. A page that holds a form draws the form's controls in the sticky
+ * header beside its title, so where the row stands and its save stay on screen
+ * on every tab.
+ */
+export const appPage = <const Main extends readonly unknown[]>(main: Main) =>
+  ({ shell: 'app', header: holdsForm(main) ? [{ title: {} }, { controls: {} }] : [{ title: {} }], main }) as const
+
+/**
+ * What an edit page's danger zone holds: the buttons a page passes, which
+ * change the row for everyone and can be taken back, first, and the delete
+ * last, which cannot. Every edit page of the dashboard ends its record layout
+ * with it, so the destructive buttons of every kayan sit in one place drawn one
+ * way, and the form's own footer holds Cancel and Save alone. The delete's
+ * confirm is a two-step dialog that says in both locales that it cannot be
+ * undone.
+ */
+export const danger = <const Before extends readonly unknown[]>(...before: Before) =>
+  [...before, { button: 'delete', label: { en: 'Delete', ar: 'حذف' } }] as const
+
+/** A page in the top-bar shell the dashboard and the portal each register as `top`. */
+export const topPage = <const Main extends readonly unknown[]>(main: Main) =>
+  ({ shell: 'top', header: [{ title: {} }], nav: [{ nav: {} }], main }) as const
+
+/**
+ * A tenant kayan's list on the backoffice: every organization's rows in the
+ * registry's list, read-only, the organization a column and a filter of each.
+ * Each row opens its `backofficeRecord` below.
+ */
+export const backofficeList = <const List extends { readonly columns: readonly unknown[] }>(path: string, list: List) =>
+  ({ list: { path, page: appPage([{ layout: 'table', main: [{ list }] }]) } }) as const
+
+/**
+ * What every tenant kayan's record on the backoffice ends its side column with:
+ * whose row it is and when it was written. No id: a record is read by its name,
+ * and the address bar holds the id.
+ */
+const record = {
+  section: 'record',
+  label: { en: 'Record', ar: 'السجل' },
+  fields: ['organization', 'createdAt', 'updatedAt'],
+} as const
+
+/**
+ * A tenant kayan's record on the backoffice, which a row of its list opens: a
+ * page that holds no form, so every leaf is drawn by its field's cell over the
+ * row and nothing on it writes. The page is not called `edit`, since an edit
+ * page holds exactly one form; the host opens a row on the page whose path
+ * carries `:id` where a kayan has no edit page. `main` holds the sections the
+ * dashboard's edit page draws the same fields in, and the side column ends with
+ * the organization and the stamps. A field the report hides is not in the
+ * projection, so it is not drawn.
+ */
+export const backofficeRecord = <const Main extends readonly unknown[], const Side extends readonly unknown[] = readonly []>({ path, main, side }: { path: string; main: Main; side?: Side }) =>
+  ({ view: { path, page: appPage([{ layout: 'record', main, side: [...(side ?? []), record] }]) } }) as const
+
+// add-on: audit-log
+/**
+ * The record's activity, which each dashboard edit page draws in its side
+ * column, drawn only for an actor the access report lets read the log: one
+ * without the key would otherwise see the panel say it could not read it. The
+ * server still refuses the read whatever the page drew.
+ */
+export const activity = { component: 'activity', when: { '$user.collections.auditLog.operations.find': { equals: true } } } as const
+
+/** The record's whole activity, searched, filtered and paged, in a tab of the edit page beside Versions, for the same actor. */
+export const activityTab = {
+  tab: 'activity',
+  label: { en: 'Activity', ar: 'النشاط' },
+  fields: [{ component: 'activityLog', when: activity.when }],
+} as const
+// end add-on: audit-log

package/template/templates/mithaq/src/mithaq/rich-text-nodes.ts

@@ -0,0 +1,19 @@
+// The Lexical node classes this project's rich text is written in: the one
+// list both halves read, the server's write and every screen's editor and
+// viewer, so neither can take a node the other does not. A node of the
+// project's own is spread after the defaults, `[...defaultNodes, CalloutNode]`,
+// and a node that draws React keeps its DOM-free class here and its React
+// subclass in the client file.
+import { defaultNodes } from 'mithaq/rich-text'
+// add-on: uploads
+import { UploadNode } from 'mithaq/rich-text'
+// end add-on: uploads
+
+export const richTextNodes = [
+  ...defaultNodes,
+  // add-on: uploads
+  // An image of the organization's own files inside the text, whose server half
+  // refuses one pointing at a kayan that holds no files.
+  UploadNode,
+  // end add-on: uploads
+]