@starci/hfs 5.0.8 → 5.1.0

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

@@ -1,4 +1,5 @@
-import type { ReactNode } from "react"
+import type { Metadata } from "next"
+import type { ReactElement, ReactNode } from "react"
 import { LocaleShell } from "@{{project}}/ui"
 import { LandingLayout, landingLayoutMetadata } from "@/features/layouts/LandingLayout"
 import { landingI18n } from "@/modules/i18n"
@@ -10,10 +11,10 @@ type LayoutProps = {
 }
 
 /** The localized document title and description of the landing. */
-export const generateMetadata = async (props: LayoutProps) => landingLayoutMetadata((await props.params).locale)
+export const generateMetadata = async (props: LayoutProps): Promise<Metadata> => landingLayoutMetadata((await props.params).locale)
 
 /** The locale segment's layout slot: the document of the address's language around the landing's chrome. */
-const Layout = async (props: LayoutProps) => (
+const Layout = async (props: LayoutProps): Promise<ReactElement> => (
     <LocaleShell {...await landingI18n.readLocaleSegment(props.params)} content={<LandingLayout content={props.children} />} />
 )
 

package/templates/fe/skeleton/apps/landing/src/features/layouts/LandingLayout/index.tsx

@@ -1,6 +1,6 @@
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
-import type { ReactNode } from "react"
+import type { ReactElement, ReactNode } from "react"
 import { SiteShell } from "@{{project}}/ui"
 import { LANDING_ROUTES } from "@/modules/routes"
 
@@ -14,7 +14,7 @@ export const landingLayoutMetadata = async (locale: string): Promise<Metadata> =
 }
 
 /** The landing's chrome, resolved on the server: the shared brand shell with the wordmark linking home, around the routed body. */
-export const LandingLayout = async (props: LandingLayoutProps) => {
+export const LandingLayout = async (props: LandingLayoutProps): Promise<ReactElement> => {
     const t = await getTranslations("landing.shell")
     return (
         <SiteShell brand={t("brand")} homeHref={LANDING_ROUTES.home}>

package/templates/fe/skeleton/apps/landing/src/features/pages/LandingLoadingPage/index.tsx

@@ -1,8 +1,9 @@
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { LoadingNotice } from "@{{project}}/ui"
 
 /** Shown while a route of the landing resolves. */
-export const LandingLoadingPage = async () => {
+export const LandingLoadingPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("landing.loading")
     return <LoadingNotice label={t("message")} />
 }

package/templates/fe/skeleton/apps/landing/src/features/pages/LandingNotFoundPage/index.tsx

@@ -1,9 +1,10 @@
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { NotFoundNotice } from "@{{project}}/ui"
 import { LANDING_ROUTES } from "@/modules/routes"
 
 /** Shown when a route of the landing calls `notFound()`. */
-export const LandingNotFoundPage = async () => {
+export const LandingNotFoundPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("landing.notFound")
     return <NotFoundNotice title={t("title")} homeLabel={t("home")} homeHref={LANDING_ROUTES.home} />
 }

package/templates/fe/skeleton/apps/landing/src/features/pages/LandingPage/index.tsx

@@ -1,3 +1,4 @@
+import type { ReactElement } from "react"
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
 import { appUrl } from "@/modules/config"
@@ -10,7 +11,7 @@ export const landingMetadata = async (): Promise<Metadata> => {
 }
 
 /** The landing page, resolved on the server: its copy from the catalog and the product app's origin from the config module. */
-export const LandingPage = async () => {
+export const LandingPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("landing.home")
     return <LandingPageBase props={{ title: t("title"), lede: t("lede"), openApp: t("openApp"), appHref: appUrl() }} />
 }

package/templates/fe/skeleton/apps/landing/src/modules/i18n/index.ts

@@ -1,4 +1,5 @@
 import { createAppI18n } from "@{{project}}/i18n"
+import type { AppI18n } from "@{{project}}/i18n"
 
 /** The landing's i18n: the product's one next-intl stack (the i18n package), with this app's own catalogs under `messages/`. */
-export const landingI18n = createAppI18n("landing", (locale) => import(`./messages/${locale}.json`))
+export const landingI18n: AppI18n = createAppI18n("landing", (locale) => import(`./messages/${locale}.json`))

package/templates/fe/skeleton/apps/landing/src/modules/i18n/request.ts

@@ -1,4 +1,7 @@
 import { landingI18n } from "./index"
+import type { AppI18n } from "@{{project}}/i18n"
 
 /** The request config next-intl's plugin loads (next.config.ts): the product stack over the landing's catalogs. */
-export default landingI18n.requestConfig
+const requestConfig: AppI18n["requestConfig"] = landingI18n.requestConfig
+
+export default requestConfig

package/templates/fe/skeleton/packages/__project__-i18n/src/index.ts

@@ -6,6 +6,7 @@ import { getMessages, getRequestConfig } from "next-intl/server"
 import { notFound } from "next/navigation"
 import { locale as routeLocale } from "next/root-params"
 import { PRODUCT_TIME_ZONE, routing } from "./routing"
+import type { ProductRouting } from "./routing"
 
 /** Loads one app's own catalog for a served locale. */
 type LoadMessages = (locale: string) => Promise<unknown>
@@ -27,6 +28,23 @@ const isLocaleReader = (value: unknown): value is () => Promise<unknown> => type
 
 const readRouteLocale = async (): Promise<unknown> => (isLocaleReader(routeLocale) ? routeLocale() : undefined)
 
+/** The language the address states, its catalog and the product time zone. */
+interface LocaleSegment {
+    readonly locale: string
+    readonly messages: AbstractIntlMessages
+    readonly timeZone: string
+}
+
+/** The navigation helpers of the product's routing (links, redirects, the locale-aware router). */
+type ProductNavigation = ReturnType<typeof createNavigation<ProductRouting["locales"], "as-needed">>
+
+/** What one app of the product reads of its next-intl stack. */
+export interface AppI18n {
+    readonly navigation: ProductNavigation
+    readonly requestConfig: ReturnType<typeof getRequestConfig>
+    readonly readLocaleSegment: (params: Promise<{ readonly locale: string }>) => Promise<LocaleSegment>
+}
+
 /**
  * The next-intl stack of one app of the product, written once here and called once by each app's `modules/i18n` (R59): the
  * product's one routing with its locale-aware navigation, the request config next-intl's plugin loads (the app's
@@ -34,7 +52,7 @@ const readRouteLocale = async (): Promise<unknown> => (isLocaleReader(routeLocal
  * the app in the text of a message its catalog lacks (`<app>:<namespace>.<key>`); `loadMessages` loads its own catalogs. A server
  * module: a client component reads the default locale from `./routing`.
  */
-export const createAppI18n = (app: string, loadMessages: LoadMessages) => ({
+export const createAppI18n = (app: string, loadMessages: LoadMessages): AppI18n => ({
     navigation: createNavigation(routing),
     /**
      * The locale is the `[locale]` route param read through `next/root-params` (`experimental.rootParams` in the app's next.config.ts,

package/templates/fe/skeleton/packages/__project__-i18n/src/proxy.ts

@@ -20,5 +20,5 @@ const negotiate = createMiddleware(routing)
  * the default and serves the default locale (vi) without a prefix. One routing table for every app; each app's `src/proxy.ts`
  * re-exports this.
  */
-export const proxy = (request: NextRequest) =>
+export const proxy = (request: NextRequest): NextResponse =>
     isUnnegotiated(request.nextUrl.pathname) ? NextResponse.next() : negotiate(request)

package/templates/fe/skeleton/packages/__project__-i18n/src/routing.ts

@@ -1,4 +1,5 @@
 import { defineRouting } from "next-intl/routing"
+import type { RoutingConfig } from "next-intl/routing"
 
 /** The locales every app of the product serves; every catalog of an app has the same keys in each. */
 const LOCALES = ["vi", "en"] as const
@@ -9,11 +10,14 @@ export const DEFAULT_LOCALE = "vi"
 /** The product's time zone: fixed, not inferred, so the server and the hydrated client format the same instant the same way. */
 export const PRODUCT_TIME_ZONE = "Asia/Ho_Chi_Minh"
 
+/** The type of the product's routing table: the served locales, no locale prefix for the default one, no localized pathnames or domains. */
+export type ProductRouting = RoutingConfig<typeof LOCALES, "as-needed", never, never>
+
 /**
  * The one routing table of the product, for the proxy, the navigation and the request config of every app: vi default, a prefix
  * only when the locale is not the default, so `/vi` means the same thing on every app.
  */
-export const routing = defineRouting({
+export const routing: ProductRouting = defineRouting({
     locales: LOCALES,
     defaultLocale: DEFAULT_LOCALE,
     localePrefix: "as-needed",

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

@@ -1,7 +1,8 @@
 import { hasLocale } from "next-intl"
 import { getMessages } from "next-intl/server"
 import { notFound } from "next/navigation"
-import type { ReactNode } from "react"
+import type { Metadata } from "next"
+import type { ReactElement, ReactNode } from "react"
 import { AppLayout, appLayoutMetadata } from "@/features/layouts/AppLayout"
 import { PRODUCT_TIME_ZONE, routing } from "@/modules/i18n"
 import { Providers } from "./providers"
@@ -14,10 +15,10 @@ type LayoutProps = {
 }
 
 /** The localized document title of this route segment. */
-export const generateMetadata = async (props: LayoutProps) => appLayoutMetadata((await props.params).locale)
+export const generateMetadata = async (props: LayoutProps): Promise<Metadata> => appLayoutMetadata((await props.params).locale)
 
 /** The locale segment's document, providers and app chrome. */
-const Layout = async (props: LayoutProps) => {
+const Layout = async (props: LayoutProps): Promise<ReactElement> => {
     const { locale } = await props.params
     if (!hasLocale(routing.locales, locale)) notFound()
     const messages = await getMessages()

package/templates/fe/skeleton-lite/apps/web/src/features/layouts/AppLayout/index.tsx

@@ -1,6 +1,6 @@
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
-import type { ReactNode } from "react"
+import type { ReactElement, ReactNode } from "react"
 import { SiteShell } from "@/components/frames/SiteShell"
 import { siteUrl } from "@/modules/config"
 import { APP_ROUTES } from "@/modules/routes"
@@ -17,7 +17,7 @@ export const appLayoutMetadata = async (locale: string): Promise<Metadata> => {
 }
 
 /** The server-resolved app chrome around the routed body. */
-export const AppLayout = async (props: AppLayoutProps) => {
+export const AppLayout = async (props: AppLayoutProps): Promise<ReactElement> => {
     const t = await getTranslations("app.shell")
     return (
         <html lang={props.locale}>

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

@@ -1,3 +1,4 @@
+import type { ReactElement } from "react"
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
 import { AppGuideOverlay } from "@/features/overlays/AppGuideOverlay"
@@ -10,7 +11,7 @@ export const appHomeMetadata = async (): Promise<Metadata> => {
 }
 
 /** The front door (the session is client-side, drawn by the blocks the page composes). */
-export const AppHomePage = async () => {
+export const AppHomePage = async (): Promise<ReactElement> => {
     const t = await getTranslations("app.home")
     return (
         <>

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

@@ -1,8 +1,9 @@
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { LoadingNotice } from "@/components/composites/LoadingNotice"
 
 /** Shown while a route resolves. */
-export const AppLoadingPage = async () => {
+export const AppLoadingPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("app.loading")
     return <LoadingNotice label={t("message")} />
 }

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

@@ -1,9 +1,10 @@
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { NotFoundNotice } from "@/components/composites/NotFoundNotice"
 import { APP_ROUTES } from "@/modules/routes"
 
 /** Shown when a route does not exist. */
-export const AppNotFoundPage = async () => {
+export const AppNotFoundPage = async (): Promise<ReactElement> => {
     const t = await getTranslations("app.notFound")
     return <NotFoundNotice title={t("title")} homeLabel={t("home")} homeHref={APP_ROUTES.home} />
 }

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

@@ -21,7 +21,7 @@ const LOCALE_HEADER = "x-next-intl-locale"
  * The request config next-intl's plugin loads. The locale is the one the middleware negotiated: this module is reachable from the proxy
  * through the navigation, and `next/root-params` can only be imported inside the app directory.
  */
-export default getRequestConfig(async () => {
+const requestConfig: ReturnType<typeof getRequestConfig> = getRequestConfig(async () => {
     const requested = (await headers()).get(LOCALE_HEADER)
     const locale = hasLocale(routing.locales, requested) ? requested : routing.defaultLocale
     return {
@@ -31,3 +31,5 @@ export default getRequestConfig(async () => {
         getMessageFallback: ({ namespace, key }) => `web:${namespace ?? ""}.${key}`,
     }
 })
+
+export default requestConfig

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

@@ -7,7 +7,11 @@ export const DEFAULT_LOCALE = "vi" as const
 export const PRODUCT_TIME_ZONE = "Asia/Ho_Chi_Minh"
 
 /** The one locale-routing table of the web app. */
-export const routing = {
+export const routing: {
+    readonly locales: typeof LOCALES
+    readonly defaultLocale: typeof DEFAULT_LOCALE
+    readonly localePrefix: "as-needed"
+} = {
     locales: LOCALES,
     defaultLocale: DEFAULT_LOCALE,
     localePrefix: "as-needed" as const,

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

@@ -1,5 +1,6 @@
 import { useSWRConfig } from "swr"
 import useSWRMutation from "swr/mutation"
+import type { SWRMutationResponse } from "swr/mutation"
 import type { GraphQLResponse } from "@/modules/api"
 import { mutateCreate{{Singular}} } from "@/modules/api/graphql/mutations/mutation-create-{{singular}}"
 import type { MutateCreate{{Singular}}Data } from "@/modules/api/graphql/mutations/types/create-{{singular}}"
@@ -12,7 +13,7 @@ export const MUTATE_CREATE_{{singularUpper}}_SWR_KEY = "MUTATE_CREATE_{{singular
  * 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 with that response.
  */
-export const useMutateCreate{{Singular}}Swr = () => {
+export const useMutateCreate{{Singular}}Swr = (): SWRMutationResponse<GraphQLResponse<MutateCreate{{Singular}}Data>, Error, string, never> => {
     const { mutate } = useSWRConfig()
     return useSWRMutation(MUTATE_CREATE_{{singularUpper}}_SWR_KEY, async () => {
         const response: GraphQLResponse<MutateCreate{{Singular}}Data> = await mutateCreate{{Singular}}({ request: {} })

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

@@ -1,4 +1,5 @@
 import useSWR from "swr"
+import type { SWRResponse } from "swr"
 import type { GraphQLResponse } from "@/modules/api"
 import { query{{Singular}} } from "@/modules/api/graphql/queries/query-{{singular}}"
 import type { Query{{Singular}}Data } from "@/modules/api/graphql/queries/types/{{singular}}"
@@ -7,7 +8,7 @@ import type { Query{{Singular}}Data } from "@/modules/api/graphql/queries/types/
 export const QUERY_{{singularUpper}}_SWR_KEY = "QUERY_{{singularUpper}}_SWR"
 
 /** One {{singular}} row of the signed-in reader by id, as its GraphQLResponse; no id, no request. */
-export const useQuery{{Singular}}Swr = (id: string | undefined) =>
+export const useQuery{{Singular}}Swr = (id: string | undefined): SWRResponse<GraphQLResponse<Query{{Singular}}Data>, Error> =>
     useSWR(
         id === undefined ? null : ([QUERY_{{singularUpper}}_SWR_KEY, id] as const),
         ([, rowId]): Promise<GraphQLResponse<Query{{Singular}}Data>> => query{{Singular}}({ request: { id: rowId } }),

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

@@ -23,7 +23,7 @@ export interface CreateAuthApolloClientOptions {
  * retry (transient network failures) -> error (report) -> timeout -> refresh (one token refresh and replay on
  * UNAUTHENTICATED) -> locale (`Accept-Language`) -> access token (`Authorization: Bearer`, from modules/auth) -> http (terminal).
  */
-export const createAuthApolloClient = ({ signal, report }: CreateAuthApolloClientOptions) =>
+export const createAuthApolloClient = ({ signal, report }: CreateAuthApolloClientOptions): ApolloClient =>
     new ApolloClient({
         link: ApolloLink.from([
             createRetryLink(),

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

@@ -19,7 +19,7 @@ export interface CreateNoAuthApolloClientOptions {
  * The anonymous Apollo client for public operations: retry -> error -> timeout -> locale -> http. It never attaches a
  * token, so a public operation stays public even for a signed-in reader.
  */
-export const createNoAuthApolloClient = ({ signal, report }: CreateNoAuthApolloClientOptions) =>
+export const createNoAuthApolloClient = ({ signal, report }: CreateNoAuthApolloClientOptions): ApolloClient =>
     new ApolloClient({
         link: ApolloLink.from([
             createRetryLink(),

package/templates/fe/transport/graphql/clients/links/attach-access-token.ts

@@ -2,7 +2,7 @@ import { SetContextLink } from "@apollo/client/link/context"
 import { contextHeaders } from "./context-headers"
 
 /** Attaches `Authorization: Bearer <access token>` from modules/auth when a session exists; an anonymous call goes out without it. */
-export const createAttachAccessTokenLink = (accessToken: () => Promise<string | undefined>) =>
+export const createAttachAccessTokenLink = (accessToken: () => Promise<string | undefined>): SetContextLink =>
     new SetContextLink(async (context) => {
         const token = await accessToken()
         if (token === undefined) return {}

package/templates/fe/transport/graphql/clients/links/error.ts

@@ -15,7 +15,7 @@ const codeOf = (error: GraphQLErrorEntry): string =>
  * Reports what came back from downstream to `report` when the app passes one. The operation maps every error to its
  * GraphQLResponse, so this link never swallows or rewrites one.
  */
-export const createErrorLink = (report?: ErrorReporter) =>
+export const createErrorLink = (report?: ErrorReporter): ErrorLink =>
     new ErrorLink(({ error, operation }) => {
         if (report === undefined) return
         if (CombinedGraphQLErrors.is(error)) {

package/templates/fe/transport/graphql/clients/links/http.ts

@@ -8,7 +8,7 @@ export interface CreateHttpLinkParams {
 }
 
 /** The terminal link: POSTs the operation to the back end's GraphQL endpoint (modules/config). */
-export const createHttpLink = ({ withCredentials = false, signal }: CreateHttpLinkParams) =>
+export const createHttpLink = ({ withCredentials = false, signal }: CreateHttpLinkParams): HttpLink =>
     new HttpLink({
         uri: graphqlUrl(),
         credentials: withCredentials ? "include" : "same-origin",

package/templates/fe/transport/graphql/clients/links/locale.ts

@@ -6,7 +6,7 @@ const documentLocale = (): string | undefined =>
     typeof document === "undefined" || document.documentElement.lang === "" ? undefined : document.documentElement.lang
 
 /** The one writer of `Accept-Language`: every operation declares the language the back end answers and localizes its errors in. */
-export const createAttachLocaleLink = (locale: () => string | undefined = documentLocale) =>
+export const createAttachLocaleLink = (locale: () => string | undefined = documentLocale): SetContextLink =>
     new SetContextLink((context) => {
         const value = locale()
         if (value === undefined) return {}

package/templates/fe/transport/graphql/clients/links/refresh-token.ts

@@ -15,7 +15,7 @@ const isUnauthenticated = (error: unknown): boolean =>
  * On an UNAUTHENTICATED answer, asks modules/auth for a fresh access token once and replays the operation with it. When no
  * token comes back (the session ended) the original error travels on.
  */
-export const createRefreshTokenLink = (refreshAccessToken: () => Promise<string | undefined>) =>
+export const createRefreshTokenLink = (refreshAccessToken: () => Promise<string | undefined>): ErrorLink =>
     new ErrorLink(({ error, operation, forward }) => {
         if (!isUnauthenticated(error) || operation.getContext()[REFRESHED] === true) return
         return new Observable((observer) => {

package/templates/fe/transport/graphql/clients/links/retry.ts

@@ -6,7 +6,7 @@ import { RETRY_POLICY } from "./options"
  * Retries a transient network failure with jittered exponential backoff. A GraphQL error is an answer of the back end and
  * is never retried. First in the chain, so every other link sees the operation once per attempt.
  */
-export const createRetryLink = () =>
+export const createRetryLink = (): RetryLink =>
     new RetryLink({
         delay: { initial: RETRY_POLICY.initialDelayMs, max: RETRY_POLICY.maxDelayMs, jitter: true },
         attempts: {

package/templates/fe/transport/graphql/clients/links/timeout.ts

@@ -2,7 +2,7 @@ import { ApolloLink, Observable } from "@apollo/client"
 import { OPERATION_TIMEOUT_MS } from "./options"
 
 /** Fails the operation when no answer arrived within the timeout; the upstream links see the timeout as an error. */
-export const createTimeoutLink = (timeoutMs = OPERATION_TIMEOUT_MS) =>
+export const createTimeoutLink = (timeoutMs: number = OPERATION_TIMEOUT_MS): ApolloLink =>
     new ApolloLink(
         (operation, forward) =>
             new Observable((observer) => {

package/templates/fe/units/page/index.tsx.tpl

@@ -1,4 +1,5 @@
 import type { Metadata } from "next"
+import type { ReactElement } from "react"
 import { getTranslations } from "next-intl/server"
 import { APP_ROUTES } from "@/modules/routes"
 import { {{Name}}Base } from "./component"
@@ -23,7 +24,7 @@ const copyOf = async (isLoading: boolean): Promise<{{Name}}BaseProps["props"]> =
 }
 
 /** The {{route}} page: a server owner that resolves its copy and composes its blocks; it reads no data. */
-export const {{Name}} = async () => <{{Name}}Base props={await copyOf(false)} />
+export const {{Name}} = async (): Promise<ReactElement> => <{{Name}}Base props={await copyOf(false)} />
 
 /** The {{route}} route's loading view: the same page drawn in skeleton mode, never a separate layout (STATE-8). */
-export const {{LoadingName}} = async () => <{{Name}}Base props={await copyOf(true)} />
+export const {{LoadingName}} = async (): Promise<ReactElement> => <{{Name}}Base props={await copyOf(true)} />

package/templates/fe/units/slot/SlotView.tsx.tpl

@@ -15,7 +15,7 @@ type SlotViewProps<T> = {
 }
 
 /** The one status view (FE-ERROR-1): every region renders its loading, forbidden, error and empty status through here. */
-export const SlotView = <T,>(props: SlotViewProps<T>) => {
+export const SlotView = <T,>(props: SlotViewProps<T>): ReactNode => {
     const { slot } = props
     if (slot.isLoading === true) return props.render(props.placeholder, true)
     if (slot.isForbidden === true) return props.forbidden === "hide" ? null : <EmptyNotice message={props.labels.forbidden} />