create-mithaq 0.0.0-stage → 0.1.1

package/template/apps/asas-tanstack/src/routes/auth.sign-in.tsx

@@ -0,0 +1,86 @@
+import { useState, type ComponentProps } from 'react'
+import { Link, createFileRoute, useNavigate } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { authArm } from '../api.ts'
+import { documentHead } from '../copy.ts'
+import { AuthBox, AuthFrame, authGate, gate, notAnEmail, redirectSearch, useRefusal } from '../auth-frame.tsx'
+import { useCopy } from './__root.tsx'
+import { wanted } from '../redirect.ts'
+
+// The password has no length rule here because the provider's sign-in has none: a wrong
+// password of any length is the one refusal it answers.
+
+export const Route = createFileRoute('/auth/sign-in')({
+  head: ({ match }) => documentHead(match.context, (t) => t('auth.signIn')),
+  // The router hands `validateSearch` whatever the URL carried; `wanted` decides what is honoured.
+  validateSearch: redirectSearch,
+  beforeLoad: gate,
+  component: SignIn,
+})
+
+function SignIn() {
+  const navigate = useNavigate()
+  const { t } = useCopy()
+  const search = Route.useSearch()
+  const refused = useRefusal()
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [pending, setPending] = useState(false)
+  const [refusal, setRefusal] = useState<string | null>(null)
+  const [left, setLeft] = useState<ReadonlySet<string>>(() => new Set())
+  const required = t('auth.required', 'This field is required.')
+  const wrong = {
+    email: () => (!email ? required : notAnEmail(email) ? t('auth.invalidEmail', 'Invalid email') : undefined),
+    password: () => (password ? undefined : required),
+  }
+  const errorOf = (box: keyof typeof wrong) => (left.has(box) ? wrong[box]() : undefined)
+  const box = (id: keyof typeof wrong, label: string | undefined, props: ComponentProps<'input'>) => (
+    <AuthBox id={id} label={label} error={errorOf(id)} onLeave={() => setLeft((already) => new Set(already).add(id))} {...props} />
+  )
+
+  const submit = async (event: React.FormEvent) => {
+    event.preventDefault()
+    setLeft(new Set(Object.keys(wrong)))
+    if (Object.values(wrong).some((check) => check())) return
+    setPending(true)
+    setRefusal(null)
+    const answered = await authArm('sign-in/email', { email, password })
+    // The project's own sentence for the provider's code, never its English `message`, since copy carries every locale.
+    if (!answered.ok) {
+      setPending(false)
+      return setRefusal(refused(answered, t('auth.failed', 'That sign-in did not work.')))
+    }
+
+    setPending(false)
+
+    // The first screen this actor enters is read only once the session exists.
+    await navigate({ to: wanted({ asked: search.redirect, home: (await authGate()).home.path }) })
+  }
+
+  return (
+    <AuthFrame title={t('auth.signIn', 'Sign in')} description={t('auth.signInDescription', 'Sign in to reach the dashboard.')}>
+      <form className="grid gap-4" noValidate onSubmit={submit}>
+        {box('email', t('auth.email', 'Email'), { autoComplete: 'email', onChange: (event) => setEmail(event.target.value), type: 'email', value: email })}
+        {box('password', t('auth.password', 'Password'), { autoComplete: 'current-password', onChange: (event) => setPassword(event.target.value), type: 'password', value: password })}
+        <Link className="-mt-2 justify-self-end text-sm text-muted-foreground underline-offset-4 hover:underline" to="/auth/forgot-password" search={{ redirect: search.redirect }}>
+          {t('auth.forgotPasswordQuestion', 'Forgot password?')}
+        </Link>
+        {/* `role="alert"` so a refusal is spoken when it appears: nothing moves the focus to it. */}
+        {refusal && (
+          <p className="text-destructive text-sm" role="alert">
+            {refusal}
+          </p>
+        )}
+        <Button disabled={pending} type="submit">
+          {pending ? t('auth.signInPending', 'Signing in…') : t('auth.signIn', 'Sign in')}
+        </Button>
+      </form>
+      <p className="mt-4 text-center text-sm text-muted-foreground">
+        {t('auth.noAccount', 'No account yet?')}{' '}
+        <Link className="text-primary underline underline-offset-4" to="/auth/sign-up" search={{ redirect: search.redirect }}>
+          {t('auth.signUp', 'Sign up')}
+        </Link>
+      </p>
+    </AuthFrame>
+  )
+}

package/template/apps/asas-tanstack/src/routes/auth.sign-up.tsx

@@ -0,0 +1,122 @@
+import { useState, type ComponentProps } from 'react'
+import { Link, createFileRoute, useNavigate } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { authArm } from '../api.ts'
+import { documentHead } from '../copy.ts'
+import { AuthBox, AuthFrame, authGate, gate, notAnEmail, redirectSearch, useRefusal } from '../auth-frame.tsx'
+import { wanted } from '../redirect.ts'
+import { useCopy } from './__root.tsx'
+
+export const Route = createFileRoute('/auth/sign-up')({
+  head: ({ match }) => documentHead(match.context, (t) => t('auth.signUp')),
+  validateSearch: redirectSearch,
+  beforeLoad: gate,
+  component: SignUp,
+})
+
+/**
+ * Better Auth requires a unique slug, so a random tail keeps same-named organizations apart.
+ * Padded before the cut, so the tail is always six characters and the slug never ends in `-`.
+ */
+const slugOf = (name: string) =>
+  `${name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'organization'}-${Math.random().toString(36).slice(2).padEnd(6, '0').slice(0, 6)}`
+
+function SignUp() {
+  const navigate = useNavigate()
+  const { t } = useCopy()
+  const search = Route.useSearch()
+  const refused = useRefusal()
+  const { password: bounds } = Route.useRouteContext()
+  // The redirect is a link anyone can write; a crafted one only makes an account with no organization,
+  // which reads nothing until an organization invites it.
+  const invited = wanted({ asked: search.redirect, home: '/' }).startsWith('/auth/accept-invitation?')
+  const [name, setName] = useState('')
+  const [organization, setOrganization] = useState('')
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [confirmation, setConfirmation] = useState('')
+  const [pending, setPending] = useState(false)
+  const [refusal, setRefusal] = useState<string | null>(null)
+  // The address this submit already signed up. A second sign-up with the same email is refused, so a
+  // retry after the organization call failed must skip it. An address and not a flag: a corrected typo signs up again.
+  const [signedUpAs, setSignedUpAs] = useState<string | null>(null)
+  const [left, setLeft] = useState<ReadonlySet<string>>(() => new Set())
+  const required = t('auth.required', 'This field is required.')
+  const wrong = {
+    name: () => (name ? undefined : required),
+    organization: () => (invited || organization ? undefined : required),
+    email: () => (!email ? required : notAnEmail(email) ? t('auth.invalidEmail', 'Invalid email') : undefined),
+    password: () =>
+      !password ? required
+      : password.length < bounds.min ? t('auth.passwordTooShort', 'Password too short')
+      : password.length > bounds.max ? t('auth.passwordTooLong', 'Password too long')
+      : undefined,
+    confirmation: () => (!confirmation ? required : confirmation === password ? undefined : t('auth.passwordsDiffer', 'The two passwords are not the same.')),
+  }
+  const errorOf = (box: keyof typeof wrong) => (left.has(box) ? wrong[box]() : undefined)
+  const box = (id: keyof typeof wrong, label: string | undefined, props: ComponentProps<'input'> & { description?: string }) => (
+    <AuthBox id={id} label={label} error={errorOf(id)} onLeave={() => setLeft((already) => new Set(already).add(id))} {...props} />
+  )
+
+  const submit = async (event: React.FormEvent) => {
+    event.preventDefault()
+    setLeft(new Set(Object.keys(wrong)))
+    if (Object.values(wrong).some((check) => check())) return
+    setPending(true)
+    setRefusal(null)
+    if (signedUpAs !== email) {
+      const made = await authArm('sign-up/email', { name, email, password })
+      if (!made.ok) {
+        setPending(false)
+        return setRefusal(refused(made, t('auth.signUpFailed', 'That sign-up did not work.')))
+      }
+      setSignedUpAs(email)
+    }
+    // A refusal here leaves an account that reads nothing, so the sentence names the organization;
+    // `signedUpAs` holds a retry to this call.
+    const created = invited ? undefined : await authArm('organization/create', { name: organization, slug: slugOf(organization) })
+    setPending(false)
+    if (created && !created.ok) return setRefusal(refused(created, t('auth.organizationFailed', 'That organization could not be created.')))
+    await navigate({ to: wanted({ asked: search.redirect, home: (await authGate()).home.path }) })
+  }
+
+  return (
+    <AuthFrame
+      title={t('auth.signUp', 'Sign up')}
+      description={invited ? t('auth.signUpInvitedDescription', 'Make an account with the email address the invitation was sent to.') : t('auth.signUpDescription', 'Make an account and its organization.')}
+    >
+      <form className="grid gap-4" noValidate onSubmit={submit}>
+        {box('name', t('auth.name', 'Name'), { autoComplete: 'name', onChange: (event) => setName(event.target.value), type: 'text', value: name })}
+        {invited ? null : box('organization', t('auth.organization', 'Organization'), { autoComplete: 'organization', onChange: (event) => setOrganization(event.target.value), type: 'text', value: organization })}
+        {box('email', t('auth.email', 'Email'), { autoComplete: 'email', onChange: (event) => setEmail(event.target.value), type: 'email', value: email })}
+        {box('password', t('auth.password', 'Password'), {
+          autoComplete: 'new-password',
+          description: t('auth.passwordRule', 'At least {count} characters.')!.replace('{count}', String(bounds.min)),
+          onChange: (event) => setPassword(event.target.value),
+          type: 'password',
+          value: password,
+        })}
+        {box('confirmation', t('auth.confirmPassword', 'Confirm the password'), {
+          autoComplete: 'new-password',
+          onChange: (event) => setConfirmation(event.target.value),
+          type: 'password',
+          value: confirmation,
+        })}
+        {refusal && (
+          <p className="text-destructive text-sm" role="alert">
+            {refusal}
+          </p>
+        )}
+        <Button disabled={pending} type="submit">
+          {pending ? t('auth.signUpPending', 'Signing up…') : t('auth.signUp', 'Sign up')}
+        </Button>
+      </form>
+      <p className="mt-4 text-center text-sm text-muted-foreground">
+        {t('auth.haveAccount', 'Already have an account?')}{' '}
+        <Link className="text-primary underline underline-offset-4" to="/auth/sign-in" search={{ redirect: search.redirect }}>
+          {t('auth.signIn', 'Sign in')}
+        </Link>
+      </p>
+    </AuthFrame>
+  )
+}

package/template/apps/asas-tanstack/src/routes/index.tsx

@@ -0,0 +1,142 @@
+import { Link, createFileRoute } from '@tanstack/react-router'
+import { BookOpen, LayoutDashboard, Languages, ShieldCheck, Users } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { useHomeLabel } from '../auth-frame.tsx'
+import { LocaleSwitch } from '../locale-switch.tsx'
+import { loadEnterable } from '../screens.tsx'
+import { useCopy } from './__root.tsx'
+
+// A host file because it reads `loadEnterable`, which only a host file may.
+export const Route = createFileRoute('/')({
+  loader: () => loadEnterable(),
+  component: Landing,
+})
+
+function EntryActions({ screens, size }: { screens: readonly { name: string; path: string }[] | null; size: 'sm' | 'lg' }) {
+  const { t } = useCopy()
+  const label = useHomeLabel()
+  if (screens === null) {
+    return (
+      <>
+        <Link to="/auth/sign-up">
+          <Button size={size}>{t('marketing.getStarted', 'Get started')}</Button>
+        </Link>
+        <Link to="/auth/sign-in">
+          <Button size={size} variant="outline">
+            {t('auth.signIn', 'Sign in')}
+          </Button>
+        </Link>
+      </>
+    )
+  }
+  // A plain anchor: the path is the screen's own data, not a route the router knows.
+  const home: { path: string; name?: string } = screens[0] ?? { path: '/unauthorized' }
+  return (
+    <a href={home.path}>
+      <Button size={size}>{label(home, 'marketing.openScreen')}</Button>
+    </a>
+  )
+}
+
+function Feature({ icon: Icon, title, description }: { icon: typeof BookOpen; title: string; description: string }) {
+  return (
+    <Card>
+      <CardHeader>
+        <Icon className="mb-2 h-6 w-6 text-primary" />
+        <CardTitle className="text-base font-semibold">{title}</CardTitle>
+      </CardHeader>
+      <CardContent className="text-sm text-muted-foreground">{description}</CardContent>
+    </Card>
+  )
+}
+
+function Step({ number, title, description }: { number: number; title: string; description: string }) {
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex h-9 w-9 items-center justify-center rounded-full bg-primary text-primary-foreground text-sm font-semibold">
+        {number}
+      </div>
+      <h3 className="font-semibold">{title}</h3>
+      <p className="text-sm text-muted-foreground">{description}</p>
+    </div>
+  )
+}
+
+function Landing() {
+  const { t, locale } = useCopy()
+  const screens = Route.useLoaderData()?.screens ?? null
+  // `t` answers `string | undefined` for a key no locale carries; the fallback only satisfies that type.
+  const tt = (key: string, fallback: string) => t(key, fallback) ?? fallback
+  const features = [
+    { icon: BookOpen, title: tt('marketing.featureCoursesTitle', 'Courses and sessions'), description: tt('marketing.featureCoursesDescription', '') },
+    { icon: Users, title: tt('marketing.featureEnrollmentsTitle', 'Enrollments'), description: tt('marketing.featureEnrollmentsDescription', '') },
+    { icon: ShieldCheck, title: tt('marketing.featureRolesTitle', 'Roles and permissions'), description: tt('marketing.featureRolesDescription', '') },
+    { icon: Languages, title: tt('marketing.featureBilingualTitle', 'Arabic and English, either direction'), description: tt('marketing.featureBilingualDescription', '') },
+    { icon: LayoutDashboard, title: tt('marketing.featurePortalTitle', 'A dashboard and a customer portal'), description: tt('marketing.featurePortalDescription', '') },
+  ]
+  const steps = [
+    { title: tt('marketing.howStep1Title', 'Set up your organization'), description: tt('marketing.howStep1Description', '') },
+    { title: tt('marketing.howStep2Title', 'Add courses and roles'), description: tt('marketing.howStep2Description', '') },
+    { title: tt('marketing.howStep3Title', 'Open the portal to your customers'), description: tt('marketing.howStep3Description', '') },
+  ]
+  return (
+    <div className="flex min-h-screen flex-col">
+      <header className="sticky top-0 z-50 border-b bg-background/80 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+        <div className="mx-auto flex h-16 max-w-6xl items-center justify-between gap-2 px-4 sm:gap-4 sm:px-6">
+          <span className="text-lg font-semibold">{t('marketing.brand', 'Asas')}</span>
+          <div className="flex items-center gap-1 sm:gap-2">
+            <LocaleSwitch locale={locale} />
+            <EntryActions screens={screens} size="sm" />
+          </div>
+        </div>
+      </header>
+
+      <main className="flex-1">
+        <section className="mx-auto flex max-w-4xl flex-col items-center gap-6 px-4 py-20 text-center sm:px-6 sm:py-28">
+          <h1 className="text-4xl font-bold tracking-tight sm:text-5xl">{t('marketing.heroTitle', 'Run courses and enrollments without the busywork')}</h1>
+          <p className="max-w-2xl text-lg text-muted-foreground">{t('marketing.heroSubtitle', '')}</p>
+          <div className="flex flex-col gap-3 sm:flex-row">
+            <EntryActions screens={screens} size="lg" />
+          </div>
+        </section>
+
+        <section className="mx-auto max-w-6xl px-4 py-16 sm:px-6">
+          <div className="mx-auto mb-12 max-w-2xl text-center">
+            <h2 className="text-3xl font-bold tracking-tight">{t('marketing.featuresTitle', 'Everything a training organization needs')}</h2>
+            <p className="mt-3 text-muted-foreground">{t('marketing.featuresSubtitle', '')}</p>
+          </div>
+          <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+            {features.map((feature) => (
+              <Feature key={feature.title} {...feature} />
+            ))}
+          </div>
+        </section>
+
+        <section className="border-t bg-muted/30">
+          <div className="mx-auto max-w-6xl px-4 py-16 sm:px-6">
+            <h2 className="mb-10 text-center text-3xl font-bold tracking-tight">{t('marketing.howTitle', 'How it works')}</h2>
+            <div className="grid gap-8 sm:grid-cols-3">
+              {steps.map((step, at) => (
+                <Step key={step.title} number={at + 1} {...step} />
+              ))}
+            </div>
+          </div>
+        </section>
+
+        <section className="mx-auto flex max-w-3xl flex-col items-center gap-6 px-4 py-20 text-center sm:px-6">
+          <h2 className="text-3xl font-bold tracking-tight">{t('marketing.ctaTitle', 'Start running your courses on Asas')}</h2>
+          <p className="text-muted-foreground">{t('marketing.ctaSubtitle', '')}</p>
+          <EntryActions screens={screens} size="lg" />
+        </section>
+      </main>
+
+      <footer className="border-t py-8">
+        <div className="mx-auto max-w-6xl px-4 text-center text-sm text-muted-foreground sm:px-6">
+          {t('marketing.footer', 'Asas — courses and enrollments for training organizations.')}
+        </div>
+      </footer>
+    </div>
+  )
+}
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 32a4513d4cf4a984b7845056965d48edff53542ce962b466af67a87983832a6d

package/template/apps/asas-tanstack/src/routes/unauthorized.tsx

@@ -0,0 +1,122 @@
+import { Fragment, useState, type ReactNode } from 'react'
+import { createFileRoute, redirect } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { authArm } from '../api.ts'
+import { AuthFrame, useRefusal } from '../auth-frame.tsx'
+import { documentHead } from '../copy.ts'
+import { ImpersonationBar, loadEnterable } from '../screens.tsx'
+import { useCopy } from './__root.tsx'
+
+export const Route = createFileRoute('/unauthorized')({
+  // The path a screen refused; the server only matches it against the build's pages.
+  validateSearch: (search: Record<string, unknown>): { from?: string } => (typeof search.from === 'string' ? { from: search.from } : {}),
+  loaderDeps: ({ search }) => ({ from: search.from }),
+  loader: async ({ deps, context }) => {
+    const entered = await loadEnterable({ data: { from: deps.from, locale: context.locale } })
+    // Carries this page's own path so a visitor whose session expired lands back here after signing in.
+    if (!entered) throw redirect({ to: '/auth/sign-in', search: { redirect: '/unauthorized' } })
+    return entered
+  },
+  // After the loader, so its data's type is inferred before this reads it.
+  head: ({ match, loaderData }) => documentHead(match.context, (t) => (loaderData?.screens.length === 0 ? t('auth.noAccess') : t('auth.unauthorized'))),
+  component: Unauthorized,
+})
+
+function Unauthorized() {
+  const { t } = useCopy()
+  const { screens, refused, email, impersonating, organizations = [], others = [] } = Route.useLoaderData()
+  const refusal = useRefusal()
+  const [switching, setSwitching] = useState<string>()
+  const [failed, setFailed] = useState<string>()
+  // The slug sits beside the name where another membership shares the name.
+  const memberships = [...organizations, ...others]
+  const named = (one: { id: string; name: string; slug?: string }): ReactNode =>
+    one.slug && memberships.some((other) => other.id !== one.id && other.name === one.name) ? (
+      <>
+        {one.name} <span dir="ltr" data-slug="" className="text-muted-foreground text-xs font-normal">{one.slug}</span>
+      </>
+    ) : (
+      one.name
+    )
+  // Each name is isolated so an email or Latin name in an Arabic sentence keeps
+  // its order, and is one inline box that wraps whole, so a long address never
+  // runs past the card on a phone.
+  const whole = 'inline-block max-w-full [overflow-wrap:anywhere]'
+  const said = (text: string | undefined) =>
+    text!.split(/(\{email\}|\{organization\}|\{page\})/).map((part, at) =>
+      part === '{email}' ? <bdi key={at} className={whole}>{email}</bdi>
+      : part === '{organization}' ? <bdi key={at}>{organizations.map((one, index) => <Fragment key={one.id}>{index ? ', ' : ''}<span className={whole}>{named(one)}</span></Fragment>)}</bdi>
+      : part === '{page}' ? <bdi key={at}>{refused?.page}</bdi>
+      : part)
+  const link = 'text-foreground underline underline-offset-4'
+  const screenName = (name: string) => t(`screens.${name}`, name) ?? name
+  return (
+    <AuthFrame
+      title={screens.length ? t('auth.unauthorized', 'Not for your role') : t('auth.noAccess', 'Your account has no access yet')}
+      description={
+        <span data-no-access={screens.length ? undefined : ''}>
+          {refused
+            ? said(t('auth.unauthorizedPage', 'Your role does not open that page: {page}.'))
+            : screens.length
+              ? t('auth.unauthorizedDescription', 'Your role does not open that screen. These are the screens it opens:')
+              : organizations.length
+                ? said(t('auth.noAccessDescription', '{email} is a member of {organization} and holds no role that opens a screen here. Ask an administrator of {organization} to give you one.'))
+                : said(t('auth.noOrganization', '{email} belongs to no organization yet. Ask an administrator to invite you.'))}
+        </span>
+      }
+    >
+      <div className="grid gap-4">
+        {/* Stopping impersonation is the way out in place of Sign out. */}
+        {impersonating ? <ImpersonationBar name={impersonating} /> : null}
+        {refused ? (
+          <a className={link} href={refused.screen.path}>
+            {(t('auth.backTo', 'Back to {screen}') ?? 'Back to {screen}').replace('{screen}', () => screenName(refused.screen.name))}
+          </a>
+        ) : screens.length ? (
+          <ul className="grid gap-2">
+            {screens.map((screen) => (
+              <li key={screen.name}>
+                {/* An anchor: the path is the screen's own data, not a route the router knows. */}
+                <a className={link} href={screen.path}>
+                  {screenName(screen.name)}
+                </a>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+        {/* So a switch into an organization where the actor holds no role is not a dead end. */}
+        {others.map((one) => (
+          <Button
+            key={one.id}
+            type="button"
+            variant="secondary"
+            data-switch-organization={one.id}
+            // Busy while it runs, so a second press sends nothing.
+            disabled={switching !== undefined}
+            aria-busy={switching === one.id || undefined}
+            onClick={() => {
+              setSwitching(one.id)
+              setFailed(undefined)
+              void authArm('organization/set-active', { organizationId: one.id }).then((answer) => {
+                if (answer.ok) return window.location.assign('/auth/sign-in')
+                setSwitching(undefined)
+                setFailed(refusal(answer, t('auth.requestFailed', 'That request did not work.')))
+              })
+            }}
+          >
+            {/* One box, so the button's gap does not open beside the name. */}
+            <span>{(t('auth.switchTo', 'Switch to {organization}') ?? 'Switch to {organization}').split(/(\{organization\})/).map((part, at) => (part === '{organization}' ? <bdi key={at}>{named(one)}</bdi> : part))}</span>
+          </Button>
+        ))}
+        {failed ? <p role="alert" className="text-destructive text-sm">{failed}</p> : null}
+        {/* `replace`, so Back does not return to the page signed out of. */}
+        {impersonating ? null : (
+          <Button type="button" variant="outline" className="max-sm:h-11" onClick={() => void authArm('sign-out').then(() => window.location.replace('/auth/sign-in'))}>
+            {t('admin.signOut', 'Sign out')}
+          </Button>
+        )}
+      </div>
+    </AuthFrame>
+  )
+}
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 3c5c304b3892c56759bf780f155ef3aa154ce3cc954e3d240b3537cdd97da735

package/template/apps/asas-tanstack/src/screen-form.tsx

@@ -0,0 +1,34 @@
+import { useBlocker, useRouter } from '@tanstack/react-router'
+import { useState, type ReactElement } from 'react'
+import { Form, type FormProps } from './components/mithaq/form.tsx'
+
+/**
+ * A kayan's form on a screen's page. A create moves to the new row's edit page, a delete to the list.
+ * While the form holds a change the router blocks navigation and the form asks its discard question.
+ */
+export function ScreenForm({ edit, list, ...props }: Omit<FormProps, 'onDone' | 'onDirty' | 'onCancel' | 'blocked'> & {
+  /** The href of a row's edit page, or nothing where the kayan has none. */
+  edit: (id: string) => string | undefined
+  /** The href of the kayan's list, or nothing where it has none. */
+  list?: string
+}): ReactElement {
+  const router = useRouter()
+  const [dirty, setDirty] = useState(false)
+  const blocker = useBlocker({ shouldBlockFn: () => dirty, withResolver: true, enableBeforeUnload: false })
+  // `ignoreBlocker`: the form reports clean only on the render after the save.
+  const go = (href: string | undefined) => void (href ? router.navigate({ href, ignoreBlocker: true }) : router.invalidate())
+  const landing = (row: unknown, effect?: string) => {
+    const id = (row as { id?: unknown } | null | undefined)?.id
+    return effect === 'delete' ? list : effect === 'create' && id !== undefined ? edit(String(id)) : undefined
+  }
+  return (
+    <Form
+      {...props}
+      onDirty={setDirty}
+      onDone={(row, effect) => go(landing(row, effect))}
+      onCancel={list ? () => go(list) : undefined}
+      blocked={blocker.status === 'blocked' ? blocker : undefined}
+    />
+  )
+}
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 7284b5e97770fd0c395fafa0b7459cab4ceb458e4bc982dc8233894126116170

package/template/apps/asas-tanstack/src/screen-list.tsx

@@ -0,0 +1,139 @@
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { useState, type ReactElement } from 'react'
+import { ListContext, useScreen } from 'mithaq/admin/react'
+import { Button } from '@/components/ui/button'
+import { List, type ListProps, type Page } from './components/mithaq/list.tsx'
+import { QueryRefused, findOf, readQuery, readRaw, rulesOf, scopedTo, writeQuery, type ListQuery, type RawQuery } from './components/mithaq/list-query.ts'
+import { counted } from './components/mithaq/controls.tsx'
+import { listOf } from './components/mithaq/nodes.tsx'
+
+/**
+ * The list's search as the router carries it: the URL's pairs as strings, each
+ * `where[…]` pair a key of its own. The router's default would JSON-quote a
+ * page number, so an app hands these two to `createRouter`.
+ */
+export const flatSearch = {
+  parseSearch: (search: string) => Object.fromEntries(new URLSearchParams(search)),
+  stringifySearch: (search: Record<string, unknown>) => {
+    const written = new URLSearchParams(Object.entries(search).flatMap(([key, value]) => (value === undefined ? [] : [[key, String(value)]]))).toString()
+    return written ? `?${written}` : ''
+  },
+}
+
+/** A page route's search: the list's own keys, each the string the URL carries, read against the list once the loader has the kayan. */
+export const askedFor = (search: Record<string, unknown>): RawQuery => readRaw(search)
+
+/** Every page of one kayan's list the browser holds, which a write to that kayan invalidates. */
+export const rowsKey = (kayan: string) => ['mithaq', kayan] as const
+
+/**
+ * Whether a list of this kayan reads with `draft: true`: the kayan keeps drafts
+ * and this actor holds `findVersions`. Then never-published rows are listed,
+ * each shown as its latest draft, and the total is counted the same way.
+ */
+export const readsDrafts = (kayan: Pick<ListProps['kayan'], 'drafts'>, operations?: Readonly<Record<string, boolean>>) =>
+  !!kayan.drafts && operations?.findVersions === true
+
+/**
+ * Whether this actor edits one row's drafts: it holds `findVersions`, and this row is within any limit on it.
+ * A row left out gets a plain Save and no autosave, since the server answers a draft save on it 404.
+ */
+export const rowReadsDrafts = async ({ kayan, operations, id, findVersions }: {
+  kayan: Pick<ListProps['kayan'], 'drafts'>
+  operations?: Readonly<Record<string, boolean>>
+  id?: string
+  findVersions: (input: { where: { parent: { equals: string } }; limit: 1 }) => Promise<{ docs: readonly unknown[] } | null>
+}) => readsDrafts(kayan, operations) && (id === undefined || !!(await findVersions({ where: { parent: { equals: id } }, limit: 1 }))?.docs.length)
+
+/** A query the URL asks for, or the sentence it was refused with, which asks nothing of the server. */
+export const queryOf = (props: Pick<ListProps, 'kayan' | 'client' | 'locales' | 'screen' | 'node'> & { maxLimit: number }, raw: RawQuery): { query: ListQuery } | { refused: string } => {
+  try {
+    return { query: readQuery(raw, rulesOf({ kayan: props.kayan, node: props.node ?? listOf(props.screen), maxLimit: props.maxLimit, context: { client: props.client, locales: props.locales } })) }
+  } catch (thrown) {
+    if (thrown instanceof QueryRefused) return { refused: thrown.message }
+    throw thrown
+  }
+}
+
+/**
+ * One screen's list, over the URL and TanStack Query. The URL is the list's one
+ * state; the server-rendered first page seeds the cache. A URL the list does
+ * not offer is refused before any request.
+ */
+export function ScreenList({
+  find,
+  first,
+  onQuery,
+  own,
+  props,
+  raw,
+  run,
+  scope,
+}: {
+  props: Omit<ListProps, 'page' | 'query' | 'onQuery' | 'run'>
+  /** The URL's search, as the route validated it. */
+  raw: RawQuery
+  onQuery: (search: Record<string, string>) => void
+  /** The page the loader read, and the input it read it with, which seeds the cache where it is the page this URL asks for. */
+  first?: { input: unknown; rows: Page }
+  find: (input: Record<string, unknown>, options?: { draft?: boolean }) => Promise<Page>
+  run: (operation: string, input: Record<string, unknown>) => Promise<unknown>
+  /** What a list node's own component draws in place of the registry's list, reading the same props through `useList()`. */
+  own?: ReactElement
+  /** The rows a list of another kayan is held to: its relationship holding the page's row. */
+  scope?: Readonly<Record<string, unknown>>
+}): ReactElement | null {
+  const queries = useQueryClient()
+  // Rows the last bulk left alone: never-published drafts, which the list shows and a bulk does not write.
+  const [left, setLeft] = useState(0)
+  const asked = queryOf({ ...props, maxLimit: useScreen().maxLimit }, raw)
+  const query = 'query' in asked ? asked.query : {}
+  const found = findOf({ kayan: props.kayan, query, node: props.node ?? listOf(props.screen), locales: props.locales, client: props.client })
+  const input = scope ? scopedTo(found, scope) : found
+  const seeded = first && JSON.stringify(first.input) === JSON.stringify(input) ? first.rows : undefined
+  const { data } = useQuery({
+    queryKey: [...rowsKey(props.kayan.name), 'find', input],
+    queryFn: () => find(input, readsDrafts(props.kayan, props.operations) ? { draft: true } : undefined),
+    enabled: 'query' in asked,
+    initialData: seeded,
+    placeholderData: (previous) => previous ?? first?.rows,
+    // Keeps the page the server just rendered from being read again as it
+    // hydrates. An organization or actor switch that does not reload the
+    // document must clear this cache, or the next actor sees the last one's pages.
+    staleTime: 30_000,
+  })
+  if ('refused' in asked) {
+    return (
+      <div role="alert" data-mithaq-refused={asked.refused} className="flex flex-col items-start gap-2 rounded-md border border-destructive/50 px-3 py-2 text-sm">
+        {props.t('admin.queryRefused', 'This link asks the list for something it does not offer, so nothing was read.')}
+        <Button type="button" variant="outline" size="sm" onClick={() => onQuery({})}>
+          {props.t('admin.clearFilters', 'Clear filters')}
+        </Button>
+      </div>
+    )
+  }
+  if (!data) return null
+  const list: ListProps = {
+    ...props,
+    page: data,
+    query,
+    onQuery: (next) => onQuery(writeQuery(next)),
+    run: async (operation, input) => {
+      const written = await run(operation, input)
+      setLeft((written as { errors?: readonly unknown[] } | null)?.errors?.length ?? 0)
+      await queries.invalidateQueries({ queryKey: rowsKey(props.kayan.name) })
+      return written
+    },
+  }
+  return (
+    <ListContext value={list}>
+      {left ? (
+        <p role="status" data-mithaq-left={left} className="rounded-md border px-3 py-2 text-sm">
+          {counted({ t: props.t, locale: props.locale, key: 'admin.bulkLeft', count: left, fallback: '{count} of the ticked rows were left as they are, because they have never been published.' })}
+        </p>
+      ) : null}
+      {own ?? <List {...list} />}
+    </ListContext>
+  )
+}
+// mithaq-admin b06d8d335d306c07556f8f2b81fba20ba7ded198 3c37825f9f645fd3f9c95a3d1ec554e863e85767e8329a1b2e16a40e5f5ea381