@btst/stack 5.1.0 → 5.2.0

package/src/plugins/job-board/client/components/shared.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { FallbackProps } from "@btst/stack/client/components";
+import {
+	usePluginOverrides,
+	usePluginSiteNavigation,
+} from "@btst/stack/context";
+import { Button } from "@workspace/ui/components/button";
+import {
+	Empty,
+	EmptyDescription,
+	EmptyHeader,
+	EmptyTitle,
+} from "@workspace/ui/components/empty";
+import { Skeleton } from "@workspace/ui/components/skeleton";
+import { cn } from "@workspace/ui/lib/utils";
+import type { EmploymentType } from "../../types";
+import { JOB_BOARD_PLUGIN_ID } from "../constants";
+import { useJobBoardLocalization } from "../hooks";
+import type { JobBoardLocalization } from "../localization";
+import type { JobBoardPluginOverrides } from "../overrides";
+
+export function JobPage({ children }: { children: ReactNode }) {
+	const { className } =
+		usePluginOverrides<JobBoardPluginOverrides>(JOB_BOARD_PLUGIN_ID);
+	return (
+		<div
+			data-testid="job-board-page"
+			className={cn(
+				"mx-auto flex w-full min-w-0 max-w-6xl flex-col gap-10 px-4 py-8 sm:px-6 sm:py-12",
+				className,
+			)}
+		>
+			{children}
+		</div>
+	);
+}
+
+export function JobLoading() {
+	const copy = useJobBoardLocalization();
+	return (
+		<JobPage>
+			<p role="status" className="text-muted-foreground">
+				{copy.loading}
+			</p>
+			<Skeleton className="h-12 w-2/3" />
+			<Skeleton className="h-24 w-full" />
+			<Skeleton className="h-24 w-full" />
+		</JobPage>
+	);
+}
+
+export function JobError({ error, resetErrorBoundary }: FallbackProps) {
+	const copy = useJobBoardLocalization();
+	return (
+		<JobPage>
+			<div role="alert" className="flex max-w-xl flex-col gap-4">
+				<h1 className="text-2xl font-semibold">{copy.errorTitle}</h1>
+				<p className="text-muted-foreground">
+					{process.env.NODE_ENV === "development" && error instanceof Error
+						? error.message
+						: copy.errorDescription}
+				</p>
+				<Button
+					className="min-h-11 self-start"
+					variant="outline"
+					onClick={resetErrorBoundary}
+				>
+					{copy.retry}
+				</Button>
+			</div>
+		</JobPage>
+	);
+}
+
+export function JobNotFound() {
+	const copy = useJobBoardLocalization();
+	const { Link, resolve } = usePluginSiteNavigation(JOB_BOARD_PLUGIN_ID);
+	return (
+		<JobPage>
+			<div className="flex max-w-xl flex-col gap-4">
+				<h1 className="text-3xl font-semibold">{copy.notFoundTitle}</h1>
+				<p className="text-muted-foreground">{copy.notFoundDescription}</p>
+				<Button className="min-h-11 self-start" variant="outline" asChild>
+					<Link href={resolve("jobs").href}>{copy.backToJobs}</Link>
+				</Button>
+			</div>
+		</JobPage>
+	);
+}
+
+export function JobsEmpty({ filtered }: { filtered: boolean }) {
+	const copy = useJobBoardLocalization();
+	return (
+		<Empty className="items-start border text-left">
+			<EmptyHeader className="items-start text-left">
+				<EmptyTitle>{copy.emptyTitle}</EmptyTitle>
+				<EmptyDescription>
+					{filtered ? copy.filteredEmptyDescription : copy.emptyDescription}
+				</EmptyDescription>
+			</EmptyHeader>
+		</Empty>
+	);
+}
+
+export function employmentLabel(
+	type: EmploymentType,
+	copy: JobBoardLocalization,
+) {
+	return {
+		"full-time": copy.fullTime,
+		"part-time": copy.partTime,
+		contract: copy.contract,
+		internship: copy.internship,
+	}[type];
+}
+
+export const jobSelectClass =
+	"border-input bg-background min-h-11 w-full min-w-0 rounded-md border px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring";

package/src/plugins/job-board/client/constants.ts

@@ -0,0 +1,2 @@
+/** Canonical client registration and override key for the Job Board plugin. */
+export const JOB_BOARD_PLUGIN_ID = "jobBoard" as const;

package/src/plugins/job-board/client/hooks/index.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import {
+	usePluginOverrides,
+	useStack,
+	useTranslate,
+} from "@btst/stack/context";
+import {
+	useInfiniteQuery,
+	useSuspenseInfiniteQuery,
+} from "@tanstack/react-query";
+import {
+	createApiClient,
+	SHARED_QUERY_CONFIG,
+} from "@btst/stack/plugins/client";
+import {
+	createResource,
+	type ResourceOverrides,
+} from "@btst/stack/plugins/client/hooks";
+import {
+	createJobBoardQueryKeys,
+	jobBoardResources,
+} from "@btst/stack/plugins/job-board/query-keys";
+import type { JobsFilters } from "../../types";
+import { JOB_BOARD_PLUGIN_ID } from "../constants";
+import {
+	jobBoardLocalization,
+	type JobBoardLocalization,
+} from "../localization";
+import type { JobBoardPluginOverrides } from "../overrides";
+
+const jobBoard = createResource({
+	plugin: JOB_BOARD_PLUGIN_ID,
+	resources: jobBoardResources,
+});
+
+function useJobListQuery(filters: JobsFilters) {
+	const { api, plugins, queryClient } = useStack();
+	const pluginApi = plugins?.[JOB_BOARD_PLUGIN_ID]?.api;
+	const { headers: overrideHeaders } =
+		usePluginOverrides<ResourceOverrides>(JOB_BOARD_PLUGIN_ID);
+	const mergedHeaders = new Headers(pluginApi?.browserHeaders);
+	if (overrideHeaders !== undefined) {
+		for (const [name, value] of new Headers(overrideHeaders)) {
+			mergedHeaders.set(name, value);
+		}
+	}
+	const headers = mergedHeaders.keys().next().done ? undefined : mergedHeaders;
+	const queries = createJobBoardQueryKeys(
+		createApiClient({
+			baseURL: pluginApi?.baseURL ?? api?.baseURL,
+			basePath: pluginApi?.basePath ?? api?.basePath,
+			headers,
+			credentials: pluginApi?.credentials,
+		}),
+	);
+	return {
+		options: { ...queries.jobBoardJobs.list(filters), ...SHARED_QUERY_CONFIG },
+		queryClient,
+	};
+}
+
+/** Paginated public jobs; filters and the cache keys match the server SSG helpers. */
+export function useJobs(filters: JobsFilters = {}) {
+	const { options, queryClient } = useJobListQuery(filters);
+	return useInfiniteQuery(options, queryClient);
+}
+
+/** Suspense variant used by the public listing and department pages. */
+export function useSuspenseJobs(filters: JobsFilters = {}) {
+	const { options, queryClient } = useJobListQuery(filters);
+	const result = useSuspenseInfiniteQuery(options, queryClient);
+	if (result.error && !result.isFetching) throw result.error;
+	return result;
+}
+
+/** Fetch one open job by its public slug. */
+export function useJob(slug: string) {
+	return jobBoard.jobBoardJobs.detail.use([slug]);
+}
+
+/** Suspense variant used by the public job detail page. */
+export function useSuspenseJob(slug: string) {
+	return jobBoard.jobBoardJobs.detail.useSuspense([slug]);
+}
+
+/** Department, location and employment-type terms from current public roles. */
+export function useJobTaxonomies() {
+	return jobBoard.jobBoardJobs.taxonomies.use([]);
+}
+
+/** Resolve public page copy from the shared translator and plugin overrides. */
+export function useJobBoardLocalization(): JobBoardLocalization {
+	const t = useTranslate();
+	const { localization } =
+		usePluginOverrides<JobBoardPluginOverrides>(JOB_BOARD_PLUGIN_ID);
+	return {
+		...Object.fromEntries(
+			Object.entries(jobBoardLocalization).map(([key, text]) => [
+				key,
+				t(`jobBoard.${key}`, text),
+			]),
+		),
+		...localization,
+	} as JobBoardLocalization;
+}
+
+/** Recheck time-sensitive visibility after hydration of a statically generated page. */
+export function useJobBoardHydrated() {
+	const [hydrated, setHydrated] = useState(false);
+	useEffect(() => setHydrated(true), []);
+	return hydrated;
+}

package/src/plugins/job-board/client/index.ts

@@ -0,0 +1,13 @@
+export { jobBoardClientPlugin } from "./plugin";
+export type {
+	JobBoardClientConfig,
+	JobBoardClientHooks,
+	JobBoardLoaderContext,
+	JobBoardOrganization,
+	JobBoardProviderConfig,
+} from "./types";
+export type { JobBoardPluginOverrides } from "./overrides";
+export {
+	jobBoardLocalization,
+	type JobBoardLocalization,
+} from "./localization";

package/src/plugins/job-board/client/localization/index.ts

@@ -0,0 +1,89 @@
+/** Copy used by the public careers pages. Values can be replaced through overrides. */
+export interface JobBoardLocalization {
+	title: string;
+	intro: string;
+	departmentTitle: string;
+	department: string;
+	allDepartments: string;
+	location: string;
+	allLocations: string;
+	employmentType: string;
+	allEmploymentTypes: string;
+	remoteOnly: string;
+	remote: string;
+	onSite: string;
+	fullTime: string;
+	partTime: string;
+	contract: string;
+	internship: string;
+	clearFilters: string;
+	viewRole: string;
+	openRoles: string;
+	loadMore: string;
+	loadingMore: string;
+	loading: string;
+	emptyTitle: string;
+	emptyDescription: string;
+	filteredEmptyDescription: string;
+	errorTitle: string;
+	errorDescription: string;
+	retry: string;
+	notFoundTitle: string;
+	notFoundDescription: string;
+	backToJobs: string;
+	aboutRole: string;
+	requirements: string;
+	salary: string;
+	closingDate: string;
+	apply: string;
+	application: string;
+	applicationDescription: string;
+	applicationsUnavailable: string;
+	workplace: string;
+}
+
+export const jobBoardLocalization: JobBoardLocalization = {
+	title: "Open roles",
+	intro: "Find a role by team, location and employment type.",
+	departmentTitle: "{department} roles",
+	department: "Department",
+	allDepartments: "All departments",
+	location: "Location",
+	allLocations: "All locations",
+	employmentType: "Employment type",
+	allEmploymentTypes: "All employment types",
+	remoteOnly: "Remote roles only",
+	remote: "Remote",
+	onSite: "On site",
+	fullTime: "Full time",
+	partTime: "Part time",
+	contract: "Contract",
+	internship: "Internship",
+	clearFilters: "Clear filters",
+	viewRole: "View role",
+	openRoles: "{count} open roles",
+	loadMore: "Show more roles",
+	loadingMore: "Loading more roles…",
+	loading: "Loading open roles…",
+	emptyTitle: "No open roles",
+	emptyDescription:
+		"There are no open positions right now. Check back for new roles.",
+	filteredEmptyDescription:
+		"No roles match these filters. Change a filter or clear them to see other positions.",
+	errorTitle: "Open roles could not be loaded",
+	errorDescription: "Check your connection and try loading the roles again.",
+	retry: "Try again",
+	notFoundTitle: "This role is no longer available",
+	notFoundDescription:
+		"The role may have closed or the link may have changed. See the current open positions.",
+	backToJobs: "All open roles",
+	aboutRole: "About the role",
+	requirements: "What you will bring",
+	salary: "Salary",
+	closingDate: "Applications close",
+	apply: "Apply for this role",
+	application: "Your application",
+	applicationDescription: "Complete the application form for this role.",
+	applicationsUnavailable: "Applications are not available for this role.",
+	workplace: "Workplace",
+};

package/src/plugins/job-board/client/overrides.ts

@@ -0,0 +1,9 @@
+import type { JobBoardLocalization } from "./localization";
+
+/** Consumer presentation overrides for the public Job Board pages. */
+export interface JobBoardPluginOverrides {
+	/** Replace individual labels and messages without changing the data layer. */
+	localization?: Partial<JobBoardLocalization>;
+	/** Additional classes on the public page container. */
+	className?: string;
+}

package/src/plugins/job-board/client/plugin.tsx

@@ -0,0 +1,224 @@
+import {
+	createApiClient,
+	createSanitizedSSRLoaderError,
+	defineClientPlugin,
+	isConnectionError,
+} from "@btst/stack/plugins/client";
+import { createJobBoardQueryKeys } from "@btst/stack/plugins/job-board/query-keys";
+import { defineRoute, defineRoutes } from "@btst/yar";
+import { lazy } from "react";
+import type { Job } from "../types";
+import { decodeJobDepartment, encodeJobDepartment } from "../utils";
+import { JOB_BOARD_PLUGIN_ID } from "./constants";
+import { jobBoardLocalization } from "./localization";
+import type { JobBoardPluginOverrides } from "./overrides";
+import type {
+	JobBoardClientConfig,
+	JobBoardLoaderContext,
+	JobBoardProviderConfig,
+} from "./types";
+
+const List = lazy(() =>
+	import("./components/pages/job-list-page").then((module) => ({
+		default: module.JobListPageComponent,
+	})),
+);
+const Detail = lazy(() =>
+	import("./components/pages/job-detail-page").then((module) => ({
+		default: module.JobDetailPageComponent,
+	})),
+);
+const Department = lazy(() =>
+	import("./components/pages/department-page").then((module) => ({
+		default: module.DepartmentPageComponent,
+	})),
+);
+
+/** Public careers routes backed by the server-filtered CMS job projection. */
+export const jobBoardClientPlugin = (config: JobBoardClientConfig = {}) =>
+	defineClientPlugin<JobBoardPluginOverrides>()({
+		id: JOB_BOARD_PLUGIN_ID,
+		providerConfig: {
+			organization: config.organization,
+		} satisfies JobBoardProviderConfig,
+		resolve: (runtime) => {
+			const queries = createJobBoardQueryKeys(
+				createApiClient({ ...runtime.api }),
+			);
+			const origin = `${runtime.site.baseURL}${runtime.site.basePath}`;
+			const listQuery = (department?: string) =>
+				queries.jobBoardJobs.list(department ? { department } : {});
+			const preload =
+				(
+					context: JobBoardLoaderContext,
+					query: {
+						queryKey: readonly unknown[];
+						queryFn: (context?: { pageParam?: unknown }) => Promise<unknown>;
+						initialPageParam?: number;
+					},
+					infinite = false,
+				) =>
+				async () => {
+					if (typeof window !== "undefined") return;
+					const fetch = (queryFn = query.queryFn, force = false) =>
+						infinite
+							? runtime.queryClient.prefetchInfiniteQuery({
+									...query,
+									queryFn,
+									initialPageParam: query.initialPageParam ?? 0,
+									retry: false,
+									...(force ? { staleTime: 0 } : {}),
+								})
+							: runtime.queryClient.prefetchQuery({
+									queryKey: query.queryKey,
+									queryFn: () => queryFn(),
+									retry: false,
+									...(force ? { staleTime: 0 } : {}),
+								});
+					let error: unknown;
+					try {
+						await config.hooks?.beforeLoad?.(context);
+						await fetch();
+						error = runtime.queryClient.getQueryState(query.queryKey)?.error;
+						if (!error) await config.hooks?.afterLoad?.(context);
+					} catch (caught) {
+						error = caught;
+						await fetch(async () => {
+							throw createSanitizedSSRLoaderError();
+						}, true);
+					}
+					if (!error) return;
+					if (isConnectionError(error))
+						console.warn(
+							"[btst/job-board] API unavailable during SSR prefetch. Use raw.jobBoard.prefetchForRoute for SSG.",
+						);
+					try {
+						await config.hooks?.onErrorLoad?.(
+							error instanceof Error ? error : new Error(String(error)),
+							context,
+						);
+					} catch {
+						// Reporting a load failure must not reject the route loader.
+					}
+				};
+			const meta = (title: string, description: string, path: string) => [
+				{ title },
+				{ name: "title", content: title },
+				{ name: "description", content: description },
+				{ property: "og:title", content: title },
+				{ property: "og:description", content: description },
+				{ property: "og:type", content: "website" },
+				{ property: "og:url", content: `${origin}${path}` },
+			];
+			return {
+				routes: () =>
+					defineRoutes(
+						{
+							jobBoardList: defineRoute("/jobs", {
+								page: List,
+								loader: preload(
+									{ routeName: "list", path: "/jobs", isSSR: true },
+									listQuery(),
+									true,
+								),
+								meta: () =>
+									meta(
+										jobBoardLocalization.title,
+										jobBoardLocalization.intro,
+										"/jobs",
+									),
+							}),
+							jobBoardDetail: defineRoute("/jobs/:slug", {
+								page: ({ params }) => <Detail slug={params.slug} />,
+								loader: ({ params }) =>
+									preload(
+										{
+											routeName: "detail",
+											path: `/jobs/${params.slug}`,
+											params,
+											isSSR: true,
+										},
+										queries.jobBoardJobs.detail(params.slug),
+									)(),
+								meta: ({ params }) => {
+									const job = runtime.queryClient.getQueryData<Job>(
+										queries.jobBoardJobs.detail(params.slug).queryKey,
+									);
+									return meta(
+										job?.title ?? jobBoardLocalization.notFoundTitle,
+										job?.description.slice(0, 200) ??
+											jobBoardLocalization.notFoundDescription,
+										`/jobs/${encodeURIComponent(params.slug)}`,
+									);
+								},
+							}),
+							jobBoardDepartment: defineRoute("/jobs/department/:dept", {
+								page: ({ params }) => (
+									<Department department={decodeJobDepartment(params.dept)} />
+								),
+								loader: async ({ params }) => {
+									const department = decodeJobDepartment(params.dept);
+									if (!department) return;
+									return preload(
+										{
+											routeName: "department",
+											path: `/jobs/department/${params.dept}`,
+											params: { dept: department },
+											isSSR: true,
+										},
+										listQuery(department),
+										true,
+									)();
+								},
+								meta: ({ params }) => {
+									const department = decodeJobDepartment(params.dept);
+									return meta(
+										department
+											? jobBoardLocalization.departmentTitle.replace(
+													"{department}",
+													department,
+												)
+											: jobBoardLocalization.notFoundTitle,
+										jobBoardLocalization.intro,
+										`/jobs/department/${params.dept}`,
+									);
+								},
+							}),
+						},
+						{
+							pages: {
+								jobBoardList: config.pageComponents?.list,
+								jobBoardDetail: config.pageComponents?.detail,
+								jobBoardDepartment: config.pageComponents?.department,
+							},
+						},
+					),
+				sitemap: async () => {
+					const jobs: Job[] = [];
+					let offset = 0;
+					while (true) {
+						const page = await queries.jobBoardJobs
+							.list({ limit: 100 })
+							.queryFn({ pageParam: offset });
+						jobs.push(...page.items);
+						offset += page.items.length;
+						if (!page.items.length || offset >= page.total) break;
+					}
+					return [
+						{ url: `${origin}/jobs`, changeFrequency: "daily" as const },
+						...jobs.map((job) => ({
+							url: `${origin}/jobs/${encodeURIComponent(job.slug)}`,
+							lastModified: job.updatedAt,
+							changeFrequency: "daily" as const,
+						})),
+						...[...new Set(jobs.map((job) => job.department))].map(
+							(department) => ({
+								url: `${origin}/jobs/department/${encodeJobDepartment(department)}`,
+								changeFrequency: "daily" as const,
+							}),
+						),
+					];
+				},
+			};
+		},
+	});

package/src/plugins/job-board/client/types.ts

@@ -0,0 +1,44 @@
+import type { ComponentType } from "react";
+
+/** Real employer information used in JobPosting structured data. */
+export interface JobBoardOrganization {
+	name: string;
+	url?: string;
+	logo?: string;
+}
+
+/** Public route being prefetched on the server. */
+export interface JobBoardLoaderContext {
+	routeName: "list" | "detail" | "department";
+	path: string;
+	params?: Record<string, string>;
+	isSSR: boolean;
+}
+
+/** Optional server-prefetch lifecycle callbacks; errors remain in the query cache. */
+export interface JobBoardClientHooks {
+	beforeLoad?: (context: JobBoardLoaderContext) => void | Promise<void>;
+	afterLoad?: (context: JobBoardLoaderContext) => void | Promise<void>;
+	onErrorLoad?: (
+		error: Error,
+		context: JobBoardLoaderContext,
+	) => void | Promise<void>;
+}
+
+/** Job Board choices; shared API, site and QueryClient values come from the stack. */
+export interface JobBoardClientConfig {
+	/** Supply the actual employer to include hiringOrganization in structured data. */
+	organization?: JobBoardOrganization;
+	hooks?: JobBoardClientHooks;
+	/** Replace public pages while preserving their routes, loaders and metadata. */
+	pageComponents?: {
+		list?: ComponentType;
+		detail?: ComponentType<{ params: { slug: string } }>;
+		department?: ComponentType<{ params: { dept: string } }>;
+	};
+}
+
+/** Serializable factory values available to the built-in public pages. */
+export interface JobBoardProviderConfig {
+	organization?: JobBoardOrganization;
+}

package/src/plugins/job-board/client.css

@@ -0,0 +1 @@
+/* Public careers pages inherit the application's theme and typography. */

package/src/plugins/job-board/index.ts

@@ -0,0 +1,14 @@
+export {
+	JOB_BOARD_CONTENT_TYPE,
+	JOB_BOARD_TYPE_SLUG,
+	jobSchema,
+} from "./schemas";
+export { isJobOpen, encodeJobDepartment, decodeJobDepartment } from "./utils";
+export type {
+	Job,
+	JobData,
+	EmploymentType,
+	JobsFilters,
+	JobsPage,
+	JobTaxonomies,
+} from "./types";

package/src/plugins/job-board/permissions.ts

@@ -0,0 +1,15 @@
+import { definePermissions, permission } from "@btst/stack/authorization";
+import { z } from "zod";
+
+/** Permissions for public job projections; CMS management retains its own permissions. */
+export const jobBoardPermissions = definePermissions("jobBoard", {
+	job: {
+		/** Read published, unexpired jobs and their public taxonomy terms. */
+		read: permission(
+			z.object({
+				scope: z.enum(["collection", "record"]),
+				slug: z.string().optional(),
+			}),
+		),
+	},
+});