@starci/hfs 4.2.13 → 4.2.15

package/templates/fe/skeleton/apps/__app__/src/modules/toast/toast.tsx

@@ -0,0 +1,32 @@
+import {
+    CheckCircleIcon,
+    ExclamationTriangleIcon,
+    InformationCircleIcon,
+    XCircleIcon,
+} from "@heroicons/react/24/outline"
+import { toast as heroToast } from "@heroui/react"
+import type { ReactNode } from "react"
+
+/** The options a status toast takes: HeroUI's, minus the variant the status already names. */
+type StatusToastOptions = Parameters<typeof heroToast.success>[1]
+
+/** The one indicator of each status, from the app's one icon set. */
+const INDICATOR: Record<"success" | "danger" | "warning" | "info", ReactNode> = {
+    success: <CheckCircleIcon className="size-6 text-success-soft-foreground" />,
+    danger: <XCircleIcon className="size-6 text-danger-soft-foreground" />,
+    warning: <ExclamationTriangleIcon className="size-6 text-warning-soft-foreground" />,
+    info: <InformationCircleIcon className="size-6 text-accent" />,
+}
+
+/** The app's toast: HeroUI's imperative toast with the status indicator injected; the region is mounted by the providers. */
+export const toast = {
+    ...heroToast,
+    success: (message: ReactNode, options?: StatusToastOptions) =>
+        heroToast.success(message, { indicator: INDICATOR.success, ...options }),
+    danger: (message: ReactNode, options?: StatusToastOptions) =>
+        heroToast.danger(message, { indicator: INDICATOR.danger, ...options }),
+    warning: (message: ReactNode, options?: StatusToastOptions) =>
+        heroToast.warning(message, { indicator: INDICATOR.warning, ...options }),
+    info: (message: ReactNode, options?: StatusToastOptions) =>
+        heroToast.info(message, { indicator: INDICATOR.info, ...options }),
+}

package/templates/fe/skeleton/apps/__app__/src/modules/types/ambient/styles.d.ts

@@ -0,0 +1,2 @@
+/** Declares stylesheets loaded by the Next bundler; non-CSS side-effect imports remain checked (noUncheckedSideEffectImports). */
+declare module "*.css" {}

package/templates/fe/skeleton/apps/__app__/src/redux/ReduxProvider.tsx

@@ -0,0 +1,11 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { Provider } from "react-redux"
+import { store } from "./store"
+
+/** What the store provider wraps: the routed tree. */
+type ReduxProviderProps = { readonly children: ReactNode }
+
+/** Mounts the app's one store above every route (components/providers/AppProviders). */
+export const ReduxProvider = (props: ReduxProviderProps) => <Provider store={store}>{props.children}</Provider>

package/templates/fe/skeleton/apps/__app__/src/redux/hooks.ts

@@ -0,0 +1,8 @@
+import { useDispatch, useSelector } from "react-redux"
+import type { AppDispatch, RootState } from "./store"
+
+/** The typed dispatch of the app's store. */
+export const useAppDispatch = useDispatch.withTypes<AppDispatch>()
+
+/** The typed selector of the app's store. */
+export const useAppSelector = useSelector.withTypes<RootState>()

package/templates/fe/skeleton/apps/__app__/src/redux/index.ts

@@ -0,0 +1,3 @@
+export { useAppDispatch, useAppSelector } from "./hooks"
+export { ReduxProvider } from "./ReduxProvider"
+export { sessionChanged } from "./slices/session"

package/templates/fe/skeleton/apps/__app__/src/redux/slices/session.ts

@@ -0,0 +1,26 @@
+import { createSlice } from "@reduxjs/toolkit"
+import type { PayloadAction } from "@reduxjs/toolkit"
+import type { AuthSession } from "@/modules/auth"
+
+/** The reader's session as the app shares it: unknown until modules/auth answers, then signed in or signed out. */
+export interface SessionState {
+    readonly status: "unknown" | "signed-in" | "signed-out"
+    readonly session?: AuthSession
+}
+
+const initialState: SessionState = { status: "unknown" }
+
+/** The session slice: written only by the auth session effect (hooks/effects), read by any component through useAppSelector. */
+export const sessionSlice = createSlice({
+    name: "session",
+    initialState,
+    reducers: {
+        sessionChanged: (_state, action: PayloadAction<AuthSession | undefined>): SessionState =>
+            action.payload === undefined ? { status: "signed-out" } : { status: "signed-in", session: action.payload },
+    },
+})
+
+/** The one action of the session slice: modules/auth reported a session (or none). */
+export const { sessionChanged } = sessionSlice.actions
+/** The reducer the store mounts under `session`. */
+export const sessionReducer = sessionSlice.reducer

package/templates/fe/skeleton/apps/__app__/src/redux/store.ts

@@ -0,0 +1,14 @@
+import { configureStore } from "@reduxjs/toolkit"
+import { sessionReducer } from "./slices/session"
+
+/** The one store of the app: app-wide shared state only (feature-local state lives in hooks/zustand). */
+export const store = configureStore({
+    reducer: {
+        session: sessionReducer,
+    },
+})
+
+/** The state of the store, for useAppSelector. */
+export type RootState = ReturnType<typeof store.getState>
+/** The dispatch of the store, for useAppDispatch. */
+export type AppDispatch = typeof store.dispatch

package/templates/fe/skeleton/apps/app/src/app/[locale]/layout.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react"
 import { LocaleShell } from "@{{project}}/ui"
+import { AppProviders } from "@/components/providers/AppProviders"
 import { AppLayout, appLayoutMetadata } from "@/features/layouts/AppLayout"
 import { appI18n } from "@/modules/i18n"
 import "../globals.css"
@@ -12,10 +13,12 @@ type LayoutProps = {
 /** The localized document title of this route segment. */
 export const generateMetadata = async (props: LayoutProps) => appLayoutMetadata((await props.params).locale)
 
-/** The locale segment's layout slot: the document of the address's language around the product app's chrome. */
+/** The locale segment's layout slot: the document of the address's language, the app's client providers and its chrome. */
 const Layout = async (props: LayoutProps) => (
     <LocaleShell {...await appI18n.readLocaleSegment(props.params)}>
-        <AppLayout content={props.children} />
+        <AppProviders>
+            <AppLayout content={props.children} />
+        </AppProviders>
     </LocaleShell>
 )
 

package/templates/fe/skeleton/apps/app/src/features/pages/AppHomePage/component.tsx

@@ -1,4 +1,6 @@
 import { Heading } from "@starci/grammar/common"
+import { SignInForm } from "@/components/blocks/SignInForm"
+import { SignOutButton } from "@/components/blocks/SignOutButton"
 
 /** Props for {@link AppHomePageBase}. */
 export type AppHomePageBaseProps = {
@@ -6,5 +8,11 @@ export type AppHomePageBaseProps = {
     readonly props: { readonly title: string }
 }
 
-/** Draw the front door of the product app. */
-export const AppHomePageBase = (props: AppHomePageBaseProps) => <Heading level={1}>{props.props.title}</Heading>
+/** Draw the front door of the product app: the sign-in form for a signed-out reader, the reader and sign-out once signed in. */
+export const AppHomePageBase = (props: AppHomePageBaseProps) => (
+    <>
+        <Heading level={1}>{props.props.title}</Heading>
+        <SignInForm />
+        <SignOutButton />
+    </>
+)

package/templates/fe/skeleton/apps/app/src/features/pages/AppHomePage/index.tsx

@@ -8,7 +8,7 @@ export const appHomeMetadata = async (): Promise<Metadata> => {
     return { title: t("title") }
 }
 
-/** The first page of the product app: a server component, so no catalog is shipped for it. */
+/** The first page of the product app: a server component; the session surface it draws runs on the client. */
 export const AppHomePage = async () => {
     const t = await getTranslations("app.home")
     return <AppHomePageBase props={{ title: t("title") }} />

package/templates/fe/skeleton/apps/app/src/modules/i18n/messages/vi.json

@@ -7,6 +7,29 @@
     "home": {
       "title": "Trang chủ"
     },
+    "signIn": {
+      "title": "Đăng nhập",
+      "email": "Email",
+      "password": "Mật khẩu",
+      "submit": "Tiếp tục",
+      "working": "Đang đăng nhập",
+      "refused": "Thông tin đăng nhập không đúng.",
+      "invalid": "Hãy nhập email và mật khẩu hợp lệ.",
+      "unavailable": "Chưa thể đăng nhập. Hãy thử lại sau."
+    },
+    "signOut": {
+      "signedIn": "Đã đăng nhập",
+      "submit": "Đăng xuất",
+      "working": "Đang đăng xuất"
+    },
+    "toast": {
+      "successTitle": "Thành công",
+      "errorTitle": "Lỗi",
+      "unauthorizedTitle": "Chưa đăng nhập",
+      "unauthorizedDescription": "Hãy đăng nhập để tiếp tục.",
+      "defaultSuccess": "Đã hoàn tất.",
+      "defaultError": "Đã xảy ra lỗi."
+    },
     "loading": {
       "message": "Đang tải"
     },

package/templates/fe/skeleton/apps/landing/src/modules/types/ambient/styles.d.ts

@@ -0,0 +1,2 @@
+/** Declares stylesheets loaded by the Next bundler; non-CSS side-effect imports remain checked (noUncheckedSideEffectImports). */
+declare module "*.css" {}

package/templates/fe/skeleton-lite/apps/__app__/src/modules/auth/client.ts

@@ -0,0 +1,51 @@
+import { createClient } from "@supabase/supabase-js"
+import type { Session, SupabaseClient } from "@supabase/supabase-js"
+import { supabaseAnonKey, supabaseUrl } from "@/modules/config"
+import type { AuthClient, AuthFailure, AuthSession } from "./contracts"
+
+let client: SupabaseClient | undefined
+
+/**
+ * The one Supabase client of the front end, used for Supabase Auth only (the PKCE flow runs in the browser: a returning
+ * redirect's code is exchanged by `detectSessionInUrl`, no route handler). It never calls `.from()`, `.rpc()` or storage:
+ * data goes through modules/api to the back end, which verifies the access token.
+ */
+const supabase = (): SupabaseClient =>
+    (client ??= createClient(supabaseUrl(), supabaseAnonKey(), {
+        auth: { flowType: "pkce", detectSessionInUrl: true, persistSession: true, autoRefreshToken: true },
+    }))
+
+const sessionOf = (session: Session | null): AuthSession | undefined =>
+    session === null
+        ? undefined
+        : { userId: session.user.id, ...(session.user.email === undefined ? {} : { email: session.user.email }) }
+
+/** A Supabase Auth error as the provider reports it: its HTTP status, its code and its message. */
+type ProviderError = { readonly status?: number; readonly code?: string; readonly message: string }
+
+/** The failure kind of a Supabase Auth error: refused credentials, rejected input, or the provider unavailable. */
+const kindOf = (status: number | undefined): string => {
+    if (status === 400 || status === 401 || status === 403) return "refused"
+    return status === 422 ? "invalid" : "unavailable"
+}
+
+/** The failure of a Supabase Auth call, or undefined when it succeeded. */
+const failureOf = (error: ProviderError | null): AuthFailure | undefined =>
+    error === null
+        ? undefined
+        : { code: error.code ?? String(error.status ?? "auth"), kind: kindOf(error.status), message: error.message }
+
+/** The identity-provider client of a lite app: Supabase Auth in the browser. */
+export const authClient: AuthClient = {
+    session: async () => sessionOf((await supabase().auth.getSession()).data.session),
+    accessToken: async () => (await supabase().auth.getSession()).data.session?.access_token,
+    refreshAccessToken: async () => (await supabase().auth.refreshSession()).data.session?.access_token,
+    signInWithPassword: async (email, password) =>
+        failureOf((await supabase().auth.signInWithPassword({ email, password })).error),
+    signOut: async () => failureOf((await supabase().auth.signOut()).error),
+    // Supabase reports INITIAL_SESSION on subscribe, then every change: the subscription alone keeps the session current.
+    onChange: (listener) => {
+        const { data } = supabase().auth.onAuthStateChange((_event, session) => listener(sessionOf(session)))
+        return () => data.subscription.unsubscribe()
+    },
+}

package/templates/fe/skeleton-lite/apps/web/src/app/[locale]/providers.tsx

@@ -2,9 +2,8 @@
 
 import { I18nProvider } from "@heroui/react"
 import { NextIntlClientProvider } from "next-intl"
-import { useEffect, type ReactNode } from "react"
-import { subscribeToAuthRefresh } from "@/modules/db/browser"
-import { navigation } from "@/modules/i18n"
+import type { ReactNode } from "react"
+import { AppProviders } from "@/components/providers/AppProviders"
 
 /** What the provider stack takes from the locale layout. */
 type ProvidersProps = {
@@ -14,13 +13,11 @@ type ProvidersProps = {
     readonly children: ReactNode
 }
 
-/** The copy, React Aria and auth-refresh contexts above every route. */
-export const Providers = (props: ProvidersProps) => {
-    const router = navigation.useRouter()
-    useEffect(() => subscribeToAuthRefresh(() => router.refresh()), [router])
-    return (
-        <NextIntlClientProvider locale={props.locale} messages={props.messages} timeZone={props.timeZone}>
-            <I18nProvider locale={props.locale}>{props.children}</I18nProvider>
-        </NextIntlClientProvider>
-    )
-}
+/** The copy and React Aria contexts above every route, around the app's client providers (components/providers). */
+export const Providers = (props: ProvidersProps) => (
+    <NextIntlClientProvider locale={props.locale} messages={props.messages} timeZone={props.timeZone}>
+        <I18nProvider locale={props.locale}>
+            <AppProviders>{props.children}</AppProviders>
+        </I18nProvider>
+    </NextIntlClientProvider>
+)

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppHomePage/component.tsx

@@ -1,14 +1,17 @@
-import { Heading, Text } from "@starci/grammar/common"
+import { Heading } from "@starci/grammar/common"
+import { SignInForm } from "@/components/blocks/SignInForm"
+import { SignOutButton } from "@/components/blocks/SignOutButton"
 
-/** Props for the signed-in home page. */
+/** Props for the home page: its title. */
 export type AppHomePageBaseProps = {
-    readonly props: { readonly title: string; readonly principal: string }
+    readonly props: { readonly title: string }
 }
 
-/** Draws the signed-in front door. */
+/** Draws the front door: the sign-in form for a signed-out reader, the reader and sign-out once signed in. */
 export const AppHomePageBase = (props: AppHomePageBaseProps) => (
     <>
         <Heading level={1}>{props.props.title}</Heading>
-        <Text>{props.props.principal}</Text>
+        <SignInForm />
+        <SignOutButton />
     </>
 )

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppHomePage/index.tsx

@@ -1,8 +1,5 @@
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
-import { SignInForm } from "@/components/blocks/SignInForm"
-import { SignOutButton } from "@/components/blocks/SignOutButton"
-import { readSession } from "@/modules/db"
 import { AppHomePageBase } from "./component"
 
 /** The document title of the home page. */
@@ -11,20 +8,8 @@ export const appHomeMetadata = async (): Promise<Metadata> => {
     return { title: t("title") }
 }
 
-/** The front door: sign-in for an anonymous request, otherwise the verified principal. */
+/** The front door (the session is client-side, drawn by the blocks the page composes). */
 export const AppHomePage = async () => {
-    const session = await readSession()
-    if (session.kind !== "ok") return <SignInForm />
     const t = await getTranslations("app.home")
-    return (
-        <>
-            <AppHomePageBase
-                props={{
-                    title: t("title"),
-                    principal: session.value.email ?? t("signedIn"),
-                }}
-            />
-            <SignOutButton />
-        </>
-    )
+    return <AppHomePageBase props={{ title: t("title") }} />
 }

package/templates/fe/skeleton-lite/apps/web/src/modules/config/index.ts

@@ -4,17 +4,10 @@ const required = (name: string, value: string | undefined): string => {
     return value
 }
 
-/** The public origin used for metadata and same-origin redirects. */
+/** The public origin used for metadata. */
 export const siteUrl = (): string => required("NEXT_PUBLIC_SITE_URL", process.env.NEXT_PUBLIC_SITE_URL)
-/** The public Supabase project origin. */
+/** The public Supabase project origin, read by modules/auth only. */
 export const supabaseUrl = (): string => required("NEXT_PUBLIC_SUPABASE_URL", process.env.NEXT_PUBLIC_SUPABASE_URL)
-/** The public anonymous key; RLS remains the authority for every request. */
+/** The public anonymous key of Supabase Auth; the back end verifies every access token it is sent. */
 export const supabaseAnonKey = (): string =>
     required("NEXT_PUBLIC_SUPABASE_ANON_KEY", process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY)
-
-/** Security attributes applied whenever the app writes a Supabase session cookie. */
-export const sessionCookieOptions = {
-    httpOnly: true,
-    secure: process.env.NODE_ENV === "production",
-    sameSite: "lax",
-} as const

package/templates/fe/skeleton-lite/apps/web/src/modules/i18n/index.ts

@@ -1,8 +1,2 @@
-import { createNavigation } from "next-intl/navigation"
-import { routing } from "./routing"
-
 /** The locale served at the unprefixed path and used by the global error boundary. */
 export { DEFAULT_LOCALE, PRODUCT_TIME_ZONE, routing } from "./routing"
-
-/** Locale-aware navigation for client components. */
-export const navigation = createNavigation(routing)

package/templates/fe/skeleton-lite/apps/web/src/modules/i18n/messages/vi.json

@@ -5,8 +5,7 @@
       "brand": "{{project}}"
     },
     "home": {
-      "title": "Home",
-      "signedIn": "Signed in"
+      "title": "Home"
     },
     "signIn": {
       "title": "Sign in",
@@ -15,17 +14,21 @@
       "submit": "Continue",
       "working": "Signing in",
       "refused": "The credentials were refused.",
-      "not-found": "The credentials were refused.",
       "invalid": "Enter a valid email and password.",
       "unavailable": "Sign-in is unavailable. Try again shortly."
     },
     "signOut": {
+      "signedIn": "Signed in",
       "submit": "Sign out",
-      "working": "Signing out",
-      "refused": "The session has already ended.",
-      "not-found": "The session has already ended.",
-      "invalid": "The session could not be ended.",
-      "unavailable": "Sign-out is unavailable. Try again shortly."
+      "working": "Signing out"
+    },
+    "toast": {
+      "successTitle": "Done",
+      "errorTitle": "Error",
+      "unauthorizedTitle": "Not signed in",
+      "unauthorizedDescription": "Sign in to continue.",
+      "defaultSuccess": "The change was saved.",
+      "defaultError": "Something went wrong."
     },
     "loading": {
       "message": "Loading"

package/templates/fe/skeleton-lite/apps/web/src/modules/routes/index.ts

@@ -1,7 +1,4 @@
 /** Every internal destination the web app links to, named once. */
 export const APP_ROUTES = {
     home: "/",
-    authCallback: "/auth/callback",
 } as const
-
-export { safeNextPath } from "./safe-next-path"

package/templates/fe/skeleton-lite/apps/web/src/proxy.ts

@@ -1,12 +1,10 @@
 import createMiddleware from "next-intl/middleware"
 import { NextResponse } from "next/server"
 import type { NextRequest } from "next/server"
-import { sessionCookieOptions } from "@/modules/config"
-import { refreshSession } from "@/modules/db"
 import { routing } from "@/modules/i18n"
-import { APP_ROUTES } from "@/modules/routes"
 
-const UNNEGOTIATED_ROOTS: ReadonlySet<string> = new Set(["auth", "health", "_next", "_vercel"])
+/** The paths outside locale routing: the liveness route and the framework's own assets. */
+const UNNEGOTIATED_ROOTS: ReadonlySet<string> = new Set(["health", "_next", "_vercel"])
 const negotiate = createMiddleware(routing)
 
 const firstSegment = (pathname: string): string => pathname.split("/")[1] ?? ""
@@ -16,28 +14,14 @@ const isUnnegotiated = (pathname: string): boolean => {
     return UNNEGOTIATED_ROOTS.has(firstSegment(pathname)) || (last.includes(".") && !last.endsWith("."))
 }
 
-const isPublic = (pathname: string): boolean =>
-    pathname === "/" || pathname === `/${routing.defaultLocale}` || isUnnegotiated(pathname)
+/**
+ * Locale routing only. The session lives in the browser (modules/auth) and the back end verifies the access token of
+ * every call, so the proxy neither reads nor refreshes it.
+ */
+export const proxy = (request: NextRequest): NextResponse =>
+    isUnnegotiated(request.nextUrl.pathname) ? NextResponse.next() : negotiate(request)
 
-/** Refreshes the Supabase session, gates private paths with verified claims, then returns locale routing. */
-export const proxy = async (request: NextRequest): Promise<NextResponse> => {
-    const response = isUnnegotiated(request.nextUrl.pathname) ? NextResponse.next() : negotiate(request)
-    const principal = await refreshSession(request, response)
-    if (principal.kind === "ok" || isPublic(request.nextUrl.pathname)) return response
-    const destination = request.nextUrl.clone()
-    destination.pathname = APP_ROUTES.home
-    destination.searchParams.set("next", request.nextUrl.pathname)
-    const redirect = NextResponse.redirect(destination)
-    for (const cookie of response.cookies.getAll()) {
-        redirect.cookies.set(cookie.name, cookie.value, {
-            ...cookie,
-            ...sessionCookieOptions,
-        })
-    }
-    return redirect
-}
-
-/** Routes that pass through session refresh and locale negotiation. */
+/** Routes that pass through locale negotiation. */
 export const config = {
     matcher: "/((?!_next/static|_next/image|favicon.ico).*)",
 }

package/templates/fe/table/graphql/mutation.ts.tpl

@@ -0,0 +1,25 @@
+import { gql } from "@apollo/client"
+import type { TypedDocumentNode } from "@apollo/client"
+import type { Create{{Singular}}Mutation, Create{{Singular}}MutationVariables } from "../__generated__/graphql"
+import { createAuthApolloClient, graphqlResponseOf } from "../clients"
+import type { GraphQLResponse, OperationParams } from "../types"
+import type { MutateCreate{{Singular}}Data, MutateCreate{{Singular}}Request } from "./types/create-{{singular}}"
+
+/** The `create{{Singular}}` mutation of the back end (be/src/features/api/{{name}}, create-{{singular}}). */
+const MUTATION_CREATE_{{singularUpper}}: TypedDocumentNode<Create{{Singular}}Mutation, Create{{Singular}}MutationVariables> = gql`
+    mutation Create{{Singular}} {
+        create{{Singular}} {
+            id
+        }
+    }
+`
+
+/** Creates one {{singular}} row owned by the signed-in reader. */
+export const mutateCreate{{Singular}} = async ({
+    request,
+    signal,
+}: OperationParams<MutateCreate{{Singular}}Request>): Promise<GraphQLResponse<MutateCreate{{Singular}}Data>> =>
+    graphqlResponseOf(
+        await createAuthApolloClient({ signal }).mutate({ mutation: MUTATION_CREATE_{{singularUpper}}, variables: request }),
+        (data) => data.create{{Singular}},
+    )

package/templates/fe/table/graphql/mutation.types.ts.tpl

@@ -0,0 +1,7 @@
+import type { Create{{Singular}}Mutation, Create{{Singular}}MutationVariables } from "../../__generated__/graphql"
+
+/** What mutateCreate{{Singular}} takes: the variables of the `create{{Singular}}` mutation (none: the caller owns the row). */
+export type MutateCreate{{Singular}}Request = Create{{Singular}}MutationVariables
+
+/** What mutateCreate{{Singular}} answers: the `create{{Singular}}` field. */
+export type MutateCreate{{Singular}}Data = Create{{Singular}}Mutation["create{{Singular}}"]

package/templates/fe/table/graphql/query.ts.tpl

@@ -0,0 +1,25 @@
+import { gql } from "@apollo/client"
+import type { TypedDocumentNode } from "@apollo/client"
+import type { {{Singular}}Query, {{Singular}}QueryVariables } from "../__generated__/graphql"
+import { createAuthApolloClient, graphqlResponseOf } from "../clients"
+import type { GraphQLResponse, OperationParams } from "../types"
+import type { Query{{Singular}}Data, Query{{Singular}}Request } from "./types/{{singular}}"
+
+/** The `{{singularCamel}}` query of the back end (be/src/features/api/{{name}}, get-{{singular}}). */
+const QUERY_{{singularUpper}}: TypedDocumentNode<{{Singular}}Query, {{Singular}}QueryVariables> = gql`
+    query {{Singular}}($input: Get{{Singular}}Input!) {
+        {{singularCamel}}(input: $input) {
+            id
+        }
+    }
+`
+
+/** Reads one {{singular}} row of the signed-in reader. */
+export const query{{Singular}} = async ({
+    request,
+    signal,
+}: OperationParams<Query{{Singular}}Request>): Promise<GraphQLResponse<Query{{Singular}}Data>> =>
+    graphqlResponseOf(
+        await createAuthApolloClient({ signal }).query({ query: QUERY_{{singularUpper}}, variables: { input: request } }),
+        (data) => data.{{singularCamel}},
+    )

package/templates/fe/table/graphql/query.types.ts.tpl

@@ -0,0 +1,7 @@
+import type { {{Singular}}Query, {{Singular}}QueryVariables } from "../../__generated__/graphql"
+
+/** What query{{Singular}} takes: the input of the `{{singularCamel}}` query (generated from the back end's contract). */
+export type Query{{Singular}}Request = {{Singular}}QueryVariables["input"]
+
+/** What query{{Singular}} answers: the `{{singularCamel}}` field. */
+export type Query{{Singular}}Data = {{Singular}}Query["{{singularCamel}}"]

package/templates/fe/table/graphql/useMutateSwr.ts.tpl

@@ -0,0 +1,21 @@
+import { useSWRConfig } from "swr"
+import useSWRMutation from "swr/mutation"
+import { mutateCreate{{Singular}} } from "@/modules/api/graphql/mutations/mutation-create-{{singular}}"
+import { QUERY_{{singularUpper}}_SWR_KEY } from "../queries/useQuery{{Singular}}Swr"
+
+/** The SWR key of the create-{{singular}} mutation. */
+export const MUTATE_CREATE_{{singularUpper}}_SWR_KEY = "MUTATE_CREATE_{{singularUpper}}_SWR"
+
+/**
+ * Creates one {{singular}} row; answers the GraphQLResponse so the caller reports it through modules/toast
+ * (useGraphQLWithToast). A success primes the {{singular}} query of the new row, the resource the mutation is tied to.
+ */
+export const useMutateCreate{{Singular}}Swr = () => {
+    const { mutate } = useSWRConfig()
+    return useSWRMutation(MUTATE_CREATE_{{singularUpper}}_SWR_KEY, async () => {
+        const response = await mutateCreate{{Singular}}({ request: {} })
+        if (response.success)
+            await mutate([QUERY_{{singularUpper}}_SWR_KEY, response.data.id], response.data, { revalidate: false })
+        return response
+    })
+}

package/templates/fe/table/graphql/useQuerySwr.ts.tpl

@@ -0,0 +1,17 @@
+import useSWR from "swr"
+import { query{{Singular}} } from "@/modules/api/graphql/queries/query-{{singular}}"
+import type { Query{{Singular}}Data } from "@/modules/api/graphql/queries/types/{{singular}}"
+
+/** The SWR key of the {{singular}} query; the full key carries the row id, the identity of its result. */
+export const QUERY_{{singularUpper}}_SWR_KEY = "QUERY_{{singularUpper}}_SWR"
+
+/** One {{singular}} row of the signed-in reader by id; no id, no request. A failure is thrown as the GraphQLResponse's message. */
+export const useQuery{{Singular}}Swr = (id: string | undefined) =>
+    useSWR(
+        id === undefined ? null : ([QUERY_{{singularUpper}}_SWR_KEY, id] as const),
+        async ([, rowId]): Promise<Query{{Singular}}Data> => {
+            const response = await query{{Singular}}({ request: { id: rowId } })
+            if (!response.success) throw new Error(response.message, { cause: response })
+            return response.data
+        },
+    )

package/templates/fe/transport/graphql/clients/clients/auth.ts

@@ -0,0 +1,39 @@
+import { ApolloClient, ApolloLink, InMemoryCache } from "@apollo/client"
+import { authClient } from "@/modules/auth"
+import {
+    createAttachAccessTokenLink,
+    createAttachLocaleLink,
+    createErrorLink,
+    createHttpLink,
+    createRefreshTokenLink,
+    createRetryLink,
+    createTimeoutLink,
+    defaultOptions,
+} from "../links"
+import type { ErrorReporter } from "../links/error"
+
+/** What the authenticated client takes: the abort signal of its operations and where the error link reports (none: it stays silent). */
+export interface CreateAuthApolloClientOptions {
+    readonly signal?: AbortSignal
+    readonly report?: ErrorReporter
+}
+
+/**
+ * The authenticated Apollo client. The link chain runs outer to inner:
+ * retry (transient network failures) -> error (report) -> timeout -> refresh (one token refresh and replay on
+ * UNAUTHENTICATED) -> locale (`x-locale`) -> access token (`Authorization: Bearer`, from modules/auth) -> http (terminal).
+ */
+export const createAuthApolloClient = ({ signal, report }: CreateAuthApolloClientOptions = {}) =>
+    new ApolloClient({
+        link: ApolloLink.from([
+            createRetryLink(),
+            createErrorLink(report),
+            createTimeoutLink(),
+            createRefreshTokenLink(() => authClient.refreshAccessToken()),
+            createAttachLocaleLink(),
+            createAttachAccessTokenLink(() => authClient.accessToken()),
+            createHttpLink({ signal }),
+        ]),
+        cache: new InMemoryCache(),
+        defaultOptions,
+    })

package/templates/fe/transport/graphql/clients/clients/index.ts

@@ -0,0 +1,2 @@
+export { createAuthApolloClient } from "./auth"
+export { createNoAuthApolloClient } from "./no-auth"